Package io.kroxylicious.proxy.filter

Interface FilterContext

public interface FilterContext
A context to allow filters to interact with other filters and the pipeline.

  • Method Details

    • channelDescriptor

      String channelDescriptor()
      A description of the downstream/client channel.
      Returns:
      A description of this channel (typically used for logging).

    • sessionId

      String sessionId()
      An id which uniquely identifies the connection with the client in both time and space. In other words this will have a different value even if a client re-establishes a TCP connection from the same IP address and source port.
      Returns:
      the ID allocated to this client session.

    • createByteBufferOutputStream

      org.apache.kafka.common.utils.ByteBufferOutputStream createByteBufferOutputStream(int initialCapacity)
      Create a ByteBufferOutputStream of the given capacity. The backing buffer will be deallocated when the request processing is completed
      Parameters:
      initialCapacity - The initial capacity of the buffer.
      Returns:
      The allocated ByteBufferOutputStream

    • sniHostname

      @Nullable String sniHostname()
      The SNI hostname provided by the client, if any.
      Returns:
      the SNI hostname provided by the client. Will be null if the client is using a non-TLS connection or the TLS client hello didn't provide one.

    • requestFilterResultBuilder

      RequestFilterResultBuilder requestFilterResultBuilder()
      Creates a builder for a request filter result objects. This object encapsulates the request to forward and optionally orders for actions such as closing the connection or dropping the request.
      The builder returns either CompletionStage<RequestFilterResult> object ready to be returned by the request filter, or a ResponseFilterResult object. The latter facilitates asynchronous programming patterns where requests must be forwarded after other work has completed.
      Returns:
      builder

    • forwardRequest

      CompletionStage<RequestFilterResult> forwardRequest(org.apache.kafka.common.message.RequestHeaderData header, org.apache.kafka.common.protocol.ApiMessage request)
      Generates a completed filter results containing the given header and request. When request filters implementations return this result, the request will be sent towards the broker, invoking upstream filters.
      Invoking this method is identical to invoking: requestFilterResultBuilder.forward(header, request).complete()
      Parameters:
      header - The header to forward to the broker.
      request - The request to forward to the broker.
      Returns:
      completed filter results.

    • sendRequest

      <M extends org.apache.kafka.common.protocol.ApiMessage> CompletionStage<M> sendRequest(org.apache.kafka.common.message.RequestHeaderData header, org.apache.kafka.common.protocol.ApiMessage request)
      Send a request from a filter towards the broker. The response to the request will be made available to the filter asynchronously, by way of the CompletionStage. The CompletionStage will contain the response object, or null of the request does not have a response.

      Header

      The caller is required to provide a RequestHeaderData. It is recommended that the caller specify the RequestHeaderData.requestApiVersion(). This can be done conveniently with forms such as:

      new RequestHeaderData().setRequestApiVersion(4)

      The caller may also provide a RequestHeaderData.clientId() an RequestHeaderData.unknownTaggedFields().

      Kroxylicious will automatically set the RequestHeaderData.requestApiKey() to be consistent with the request. RequestHeaderData.correlationId() is ignored.

      Filtering

      The request will pass through all filters upstream of the filter that invoked the operation, invoking them. Similarly, the response will pass through all filters upstream of the filter that invoked the operation, invoking them, but not itself. The response does not pass through filters downstream.

      Chained Computation stages

      Default and asynchronous default computation stages chained to the returned CompletionStage are guaranteed to be executed by the thread associated with the connection. See io.kroxylicious.proxy.filter for more details.

      Type Parameters:
      M - The type of the response
      Parameters:
      header - The request header.
      request - The request data.
      Returns:
      CompletionStage that will yield the response.
      See Also:

    • topicNames

      CompletionStage<TopicNameMapping> topicNames(Collection<org.apache.kafka.common.Uuid> topicIds)
      Attempts to map all the given topicIds to the current corresponding topic names.
      Parameters:
      topicIds - topic ids to map to names
      Returns:
      a CompletionStage that will be completed with a complete mapping, with every requested topic id mapped to either an TopicNameMappingException or a name. All failure modes should complete the stage with a TopicNameMapping, with the TopicNameMapping used to convey the reason for failure, rather than failing the Stage.

      Chained Computation stages

      Default and asynchronous default computation stages chained to the returned CompletionStage are guaranteed to be executed by the thread associated with the connection. See io.kroxylicious.proxy.filter for more details.

    • forwardResponse

      CompletionStage<ResponseFilterResult> forwardResponse(org.apache.kafka.common.message.ResponseHeaderData header, org.apache.kafka.common.protocol.ApiMessage response)
      Generates a completed filter results containing the given header and response. When response filters implementations return this result, the response will be sent towards the client, invoking downstream filters.
      Invoking this method is identical to invoking: responseFilterResultBuilder.forward(header, response).complete()
      Parameters:
      header - The header to forward to the broker.
      response - The request to forward to the broker.
      Returns:
      completed filter results.

    • responseFilterResultBuilder

      ResponseFilterResultBuilder responseFilterResultBuilder()
      Creates a builder for a request filter result objects. This object encapsulates the response to forward and optionally orders for actions such as closing the connection or dropping the response.
      The builder returns either CompletionStage<ResponseFilterResult> object ready to be returned by the response filter, or a ResponseFilterResult object. The latter facilitates asynchronous programming patterns where responses must be forwarded after other work has completed.
      Returns:
      builder

    • getVirtualClusterName

      String getVirtualClusterName()
      Allows the filter to identify which cluster it is processing a request for
      Returns:
      virtual cluster name

    • clientTlsContext

      Optional<ClientTlsContext> clientTlsContext()
      Returns the TLS context for the client connection.
      Returns:
      the TLS context, or empty if the client connection is not TLS.

    • clientSaslAuthenticationSuccess

      void clientSaslAuthenticationSuccess(String mechanism, Subject subject)
      Allows a filter (typically one which implements SaslAuthenticateRequestFilter) to announce a successful authentication outcome with the Kafka client to other plugins. After calling this method the results of clientSaslContext() and authenticatedSubject() will both be non-empty for this and other filters. In order to support reauthentication, calls to this method and clientSaslAuthenticationFailure(String, String, Exception) may be arbitrarily interleaved during the lifetime of a given filter instance.
      Parameters:
      mechanism - The SASL mechanism used
      subject - The subject

    • clientSaslAuthenticationFailure

      void clientSaslAuthenticationFailure(@Nullable String mechanism, @Nullable String authorizedId, Exception exception)
      Allows a filter (typically one which implements SaslAuthenticateRequestFilter) to announce a failed authentication outcome with the Kafka client. After calling this method the result of clientSaslContext() will be empty for this and other filters. It is the filter's responsibility to return the right error response to a client, and/or disconnect. In order to support reauthentication, calls to this method and clientSaslAuthenticationSuccess(String, Subject) may be arbitrarily interleaved during the lifetime of a given filter instance.
      Parameters:
      mechanism - The SASL mechanism used, or null if this is not known.
      authorizedId - The authorizedId, or null if this is not known.
      exception - An exception describing the authentication failure.

    • clientSaslContext

      Optional<ClientSaslContext> clientSaslContext()
      Returns the SASL context for the client connection.
      Returns:
      the SASL context, or empty if the client has not successfully authenticated using SASL.

    • authenticatedSubject

      Subject authenticatedSubject()

      Returns the client subject.

      Depending on configuration, the subject can be based on network-level or Kafka protocol-level information (or both):

      • This will return an anonymous Subject (one with an empty principals set) when no authentication is configured, or the transport layer cannot provide authentication (e.g. TCP or non-mutual TLS transports).
      • When client mutual TLS authentication is configured this will initially return a non-anonymous Subject based on the TLS certificate presented by the client.
      • At any point, if a filter invokes clientSaslAuthenticationSuccess(String, Subject) then that subject will override the existing subject.
      • Because of the possibility of reauthentication it is also possible for the subject to change even after then initial SASL reauthentication.

      Because the subject can change, callers are advised to be careful to avoid caching subjects, or decisions derived from them.

      Which principals are present in the returned subject, and what their names look like, depends on the configuration of network and/or clientSaslAuthenticationSuccess(String, Subject)-calling filters. In general, filters should be configurable with respect to the principal type when interrogating the returned subject.

      Returns:
      The client subject
      See Also: