Package com.ultikits.ultitools.utils

Class FramedChannel

java.lang.Object
com.ultikits.ultitools.utils.FramedChannel
All Implemented Interfaces:
CloudChannel
final class FramedChannel extends Object implements CloudChannel
Frames protocol replies over a socket handoff, enforcing correlation and UTF-8 frame limits. Oversized replies send a small correlated error instead, while returning false for the original reply. No payload validation is performed here.

  • Field Details

  • Constructor Details

    • FramedChannel

      FramedChannel(Predicate<String> socketSend, BooleanSupplier established, Supplier<CloudLimits> limits, Supplier<String> ids, LongSupplier clock)
      Binds framing to one connection's lifecycle; suppliers must be safe on calling threads.
      Parameters:
      socketSend - returns true only after handing the frame to the socket
      established - true only between accepted welcome and close
      limits - current accepted limits, or defaults before welcome
      ids - supplies a fresh valid ULID for each outgoing frame
      clock - supplies epoch milliseconds for outgoing timestamps

  • Method Details

    • isOpen

      public boolean isOpen()
      Description copied from interface: CloudChannel
      Reports protocol readiness, not merely whether the socket is connected.
      Specified by:
      isOpen in interface CloudChannel
      Returns:
      true only after an accepted welcome and before the connection closes

    • limits

      public CloudLimits limits()
      Description copied from interface: CloudChannel
      Returns the current connection's accepted limits, or defaults before welcome.
      Specified by:
      limits in interface CloudChannel
      Returns:
      the immutable limits snapshot

    • send

      public boolean send(String type, com.google.gson.JsonObject payload)
      Description copied from interface: CloudChannel
      Sends a message with a fresh id and timestamp, without a replyTo field.
      Specified by:
      send in interface CloudChannel
      Parameters:
      type - a registered message type that does not require replyTo
      payload - the schema-valid message payload
      Returns:
      true if the requested frame was handed to the socket

    • sendTracked

      public String sendTracked(String type, com.google.gson.JsonObject payload)
      Description copied from interface: CloudChannel
      Sends a message with a fresh id and timestamp, without a replyTo field, and reports the envelope id it used so the caller can correlate a later reply to this frame.

      The default implementation cannot report the id and refuses; channels used by the framework implement it so the id and the send path cannot diverge from CloudChannel.send(java.lang.String, com.google.gson.JsonObject).

      Specified by:
      sendTracked in interface CloudChannel
      Parameters:
      type - a registered message type that does not require replyTo
      payload - the schema-valid message payload
      Returns:
      the envelope id of the frame handed to the socket, or null when nothing was handed off, including a closed channel or an oversized frame

    • sendTracked

      public String sendTracked(String type, com.google.gson.JsonObject payload, Consumer<String> beforeHandOff)
      Description copied from interface: CloudChannel
      Sends like CloudChannel.sendTracked(String, JsonObject), but hands the envelope id to beforeHandOff before the frame reaches the socket. A caller that correlates the reply registers its pending entry there, so a reply processed on another thread can never arrive before the entry exists. When the result is null the frame was not handed off and the caller rolls its registration back; the hook may then have run or not.
      Specified by:
      sendTracked in interface CloudChannel
      Parameters:
      type - a registered message type that does not require replyTo
      payload - the schema-valid message payload
      beforeHandOff - receives the envelope id before the hand-off; must not block or throw
      Returns:
      the envelope id of the frame handed to the socket, or null when nothing was handed off

    • reply

      public boolean reply(String replyTo, String type, com.google.gson.JsonObject payload)
      Description copied from interface: CloudChannel
      Sends a correlated reply with a fresh id and timestamp.
      Specified by:
      reply in interface CloudChannel
      Parameters:
      replyTo - the request's ULID, never null
      type - a registered message type that allows replyTo
      payload - the schema-valid reply payload
      Returns:
      true if the requested reply was handed to the socket

    • replyOk

      public boolean replyOk(String replyTo, String type, com.google.gson.JsonElement data)
      Description copied from interface: CloudChannel
      Replies with an OpOutcome payload containing status: ok and data.
      Specified by:
      replyOk in interface CloudChannel
      Parameters:
      replyTo - the request's ULID
      type - the result message type
      data - result data matching that type's schema, including JSON null where allowed
      Returns:
      true if the requested reply was handed to the socket

    • replyOk

      public boolean replyOk(String replyTo, String type, com.google.gson.JsonElement data, String messageOrNull)
      Description copied from interface: CloudChannel
      Replies with an OpOutcome payload containing status: ok, data and an optional message, for result types whose ok variant declares one.

      A channel that cannot carry the message refuses instead of silently dropping it, so a caller never believes an explanation reached the panel when it did not.

      Specified by:
      replyOk in interface CloudChannel
      Parameters:
      replyTo - the request's ULID
      type - the result message type
      data - result data matching that type's schema, including JSON null where allowed
      messageOrNull - a safe result message (1..500 characters), or null to omit it
      Returns:
      true if the requested reply was handed to the socket

    • replyPartial

      public boolean replyPartial(String replyTo, String type, com.google.gson.JsonElement data, String codeOrNull, String messageOrNull)
      Description copied from interface: CloudChannel
      Replies with status: partial; only result types declaring partial allow this.
      Specified by:
      replyPartial in interface CloudChannel
      Parameters:
      replyTo - the request's ULID
      type - the result message type
      data - partial result data matching that type's schema
      codeOrNull - an allowed result code, or null to omit it
      messageOrNull - a safe result message, or null to omit it
      Returns:
      true if the requested reply was handed to the socket

    • replyError

      public boolean replyError(String replyTo, String type, String code, String message, com.google.gson.JsonObject detailsOrNull)
      Description copied from interface: CloudChannel
      Replies with code, message and optional details. Result types include status: error; the generic error type omits status.
      Specified by:
      replyError in interface CloudChannel
      Parameters:
      replyTo - the request's ULID
      type - the result message type or error
      code - an error code allowed for that type
      message - a safe diagnostic, never a credential or raw exception message
      detailsOrNull - schema-valid details, or null to omit them
      Returns:
      true if the requested reply was handed to the socket

    • frameTracked

      private String frameTracked(String replyTo, String type, com.google.gson.JsonObject payload, Consumer<String> beforeHandOff)