Interface WebRequestGateway

All Superinterfaces:
HasLocalHandlers, Namespaced<WebRequestGateway>
All Known Implementing Classes:
DefaultWebRequestGateway
public interface WebRequestGateway extends Namespaced<WebRequestGateway>, HasLocalHandlers
Gateway for sending outbound web requests via Fluxzero's proxy mechanism or the SDK's native HTTP client.

By default, this gateway logs the request as a WebRequest message, which is then picked up by the Fluxzero Runtime's proxy. Enabling useNativeHttpClient in WebRequestSettings instead executes an absolute HTTP(S) request directly from the application. Native execution deliberately bypasses message logging and local handlers.

Benefits of this approach include:

  • Traceability: Proxy-routed outbound web traffic is traceable through Fluxzero message logs.
  • Centralization: Outgoing requests are routed via a centralized proxy, simplifying firewalling and monitoring.
  • Proxy-level enhancements: The proxy can apply retries, circuit breakers, filtering, and other behaviors.

This gateway also supports local request handlers, meaning that annotated methods (e.g., @HandleWebRequest) can respond to requests directly within the application if desired.

See Also:

  • Field Details

    • defaultSettings

      static final WebRequestSettings defaultSettings
      Default request settings used when none are specified explicitly.

  • Method Details

    • sendAndForget

      CompletableFuture<Void> sendAndForget(io.fluxzero.common.Guarantee guarantee, WebRequest... requests)
      Sends one or more web requests without waiting for a response.

      Use this for fire-and-forget scenarios (e.g., async webhook posts).

      Parameters:
      guarantee - indicates whether to wait until the request is sent or stored
      requests - the web requests to send
      Returns:
      a future that completes once the requests have been sent or stored

    • send

      default CompletableFuture<WebResponse> send(WebRequest request)
      Sends the given web request using default request settings and returns a future that completes with the response.

      Proxy and native HTTP execution require an absolute URL; relative URLs may be handled by a local web handler.

      Parameters:
      request - the web request to send
      Returns:
      a future completed with the WebResponse

    • send

      CompletableFuture<WebResponse> send(WebRequest request, WebRequestSettings settings)
      Sends the given web request using given request settings and returns a future that completes with the response.

      Proxy and native HTTP execution require an absolute URL; relative URLs may be handled by a local web handler. Cancelling the returned future for a native request also cancels its active HTTP call or pending retry delay on a best-effort basis.

      Parameters:
      request - the web request to send
      Returns:
      a future completed with the WebResponse

    • sendAndWait

      default WebResponse sendAndWait(WebRequest request)
      Sends the given web request using default request settings and waits for the response synchronously.

      This method blocks the calling thread until the request is completed or times out.

      Proxy and native HTTP execution require an absolute URL; relative URLs may be handled by a local web handler.

      Parameters:
      request - the web request to send
      Returns:
      the received WebResponse

    • sendAndWait

      WebResponse sendAndWait(WebRequest request, WebRequestSettings settings)
      Sends the given web request using the specified request settings and waits for the response synchronously.

      This method blocks the calling thread until the request is completed or times out.

      Proxy and native HTTP execution require an absolute URL; relative URLs may be handled by a local web handler.

      Parameters:
      request - the web request to send
      settings - configuration settings for this request (e.g., timeouts, accepted encodings)
      Returns:
      the received WebResponse

    • close

      void close()
      Gracefully shuts down the gateway and releases any associated resources.