Class WebRequest

java.lang.Object
io.fluxzero.sdk.common.Message
io.fluxzero.sdk.web.WebRequest
All Implemented Interfaces:
HasMetadata, HasMessage
public class WebRequest extends Message
Represents a web request message within the Fluxzero Runtime.

This message is routed to handlers using annotations like HandleWeb, HandleGet, or HandleSocketOpen.

WebRequest extends Message and includes additional metadata such as:

  • path – the requested URI path including query parameters
  • method – HTTP or WebSocket method (e.g. GET, WS_OPEN)
  • headers – structured request headers
  • cookies – parsed from the Cookie header

It also provides a fluent WebRequest.Builder API to construct requests programmatically.

Example Usage

WebRequest request = WebRequest.post("https://api.example.com/projects")
    .body(new ProjectDetails("My Project", "My Description"))
    .build();

Outbound requests with an absolute URL that are dispatched using the WebRequestGateway are forwarded by the proxy in Fluxzero Runtime by default, or can be executed by the SDK's native HTTP client through WebRequestSettings.

See Also:

  • Field Details

  • Constructor Details

    • WebRequest

      public WebRequest(Message m)
      Constructs a new WebRequest instance using the provided Message.
      Parameters:
      m - the Message instance containing the payload, metadata, message ID, and timestamp

  • Method Details

    • builder

      public static WebRequest.Builder builder()
      Creates a new WebRequest.Builder instance for constructing a WebRequest.

    • get

      public static WebRequest.Builder get(String url)
      Creates a new WebRequest.Builder instance for constructing a GET request to given url.

    • post

      public static WebRequest.Builder post(String url)
      Creates a new WebRequest.Builder instance for constructing a POST request to given url.

    • put

      public static WebRequest.Builder put(String url)
      Creates a new WebRequest.Builder instance for constructing a PUT request to given url.

    • patch

      public static WebRequest.Builder patch(String url)
      Creates a new WebRequest.Builder instance for constructing a PATCH request to given url.

    • delete

      public static WebRequest.Builder delete(String url)
      Creates a new WebRequest.Builder instance for constructing a DELETE request to given url.

    • serialize

      public SerializedMessage serialize(Serializer serializer)
      Serializes the request using the content type if applicable.
      Overrides:
      serialize in class Message

    • withMetadata

      public WebRequest withMetadata(Metadata metadata)

    • addMetadata

      public WebRequest addMetadata(Metadata metadata)
      Description copied from class: Message
      Returns a new message with the combined metadata.
      Overrides:
      addMetadata in class Message

    • addMetadata

      public WebRequest addMetadata(String key, Object value)
      Description copied from class: Message
      Adds a single metadata entry.
      Overrides:
      addMetadata in class Message

    • addMetadata

      public WebRequest addMetadata(Object... keyValues)
      Description copied from class: Message
      Adds multiple metadata entries.
      Overrides:
      addMetadata in class Message

    • addMetadata

      public WebRequest addMetadata(Map<String,?> values)
      Description copied from class: Message
      Adds metadata from a given map.
      Overrides:
      addMetadata in class Message

    • addUser

      public WebRequest addUser(User user)
      Description copied from class: Message
      Attaches a user object to the metadata using the configured UserProvider.
      Overrides:
      addUser in class Message

    • withPayload

      public WebRequest withPayload(Object payload)
      Description copied from class: Message
      Returns a new message instance with the provided payload and existing metadata, ID, and timestamp.
      Overrides:
      withPayload in class Message

    • withMessageId

      public WebRequest withMessageId(String messageId)

    • withTimestamp

      public WebRequest withTimestamp(Instant timestamp)

    • getHeader

      public String getHeader(String name)
      Returns a single header value, or null if not present.
      Parameters:
      name - the header name
      Returns:
      the first value or null

    • getHeaders

      public List<String> getHeaders(String name)
      Returns all values for the specified header.
      Parameters:
      name - the header name
      Returns:
      list of values, possibly empty

    • getContentType

      public String getContentType()
      Returns the content type of the request (based on Content-Type header).

    • getPayloadAs

      public <R> R getPayloadAs(Type type)
      Deserializes the payload into a given type, using JSON if content type is application/json.
      Type Parameters:
      R - the expected payload type
      Parameters:
      type - the target type
      Returns:
      deserialized payload

    • getCookie

      public Optional<HttpCookie> getCookie(String name)
      Finds the first cookie with the given name in logical wire order.

      This method retains its first-match behavior and is equivalent to calling getCookie(String, CookieValueConflictPolicy) with CookieValueConflictPolicy.DEFAULT. Cookies in later Cookie header values are now included in the lookup.

      Parameters:
      name - the case-sensitive cookie name
      Returns:
      the first matching cookie, or empty if it is absent

    • getCookie

      public Optional<HttpCookie> getCookie(String name, CookieValueConflictPolicy conflictPolicy)
      Finds a cookie with the given name using the requested conflict policy.

      Identical repeated values are accepted by both policies. CookieValueConflictPolicy.REJECT_CONFLICTING_VALUES throws a redacted CookieConflictException when at least one matching value differs.

      Parameters:
      name - the case-sensitive cookie name
      conflictPolicy - the policy for matching cookies with different values
      Returns:
      the first matching cookie, or empty if it is absent
      Throws:
      CookieConflictException - if conflicting values are present and rejection is requested

    • getCookies

      public List<HttpCookie> getCookies(String name)
      Returns all cookies with the given name in logical wire order, without collapsing duplicates.
      Parameters:
      name - the case-sensitive cookie name
      Returns:
      all matching cookies, possibly empty

    • getPath

      @NonNull public @NonNull String getPath()
      The request path including query parameters (e.g. "/api/users?id=123"). May contain the full URL for outbound web requests.

    • getMethod

      @NonNull public @NonNull String getMethod()
      The HTTP or WebSocket method (e.g. "GET", "POST", "WS_OPEN").

    • getHeaders

      @NonNull public @NonNull Map<String, List<String>> getHeaders()
      The HTTP headers as a case-insensitive map. Header values are lists to support repeated headers.

    • toBuilder

      public WebRequest.Builder toBuilder()
      Creates a mutable builder for this request.

    • getUrl

      public static String getUrl(Metadata metadata)
      Extracts the request path from the provided Metadata object.
      Parameters:
      metadata - the metadata object containing the request path information
      Returns:
      the request path as a string
      Throws:
      IllegalStateException - if the request path information is missing in the metadata

    • getPathForLogging

      public static String getPathForLogging(Metadata metadata)
      Extracts a bounded request path that is safe to include in logs, metrics and error reports.

      The origin, query string and fragment are intentionally omitted because they may contain credentials or ceremony state. Use getUrl(Metadata) when the complete request target is required for request handling.

      Parameters:
      metadata - the request metadata
      Returns:
      the path without origin, query string or fragment, limited to 512 characters

    • getMethod

      public static String getMethod(Metadata metadata)
      Extracts the HTTP or WebSocket method (e.g., "GET", "POST", "WS_OPEN") from the provided Metadata object.
      Parameters:
      metadata - the metadata object containing the method information
      Returns:
      the HTTP or WebSocket method as a string
      Throws:
      IllegalStateException - if the method information is missing in the metadata

    • getHeaders

      public static Map<String, List<String>> getHeaders(Metadata metadata)
      Retrieves a case-insensitive map of headers from the provided Metadata object.

    • getHeader

      public static Optional<String> getHeader(Metadata metadata, String name)
      Retrieves the first header value for the given name from the provided Metadata object.

    • getCookie

      public static Optional<HttpCookie> getCookie(Metadata metadata, String name)
      Retrieves the first cookie with the given name from the provided Metadata object.

    • getSocketSessionId

      public static String getSocketSessionId(Metadata metadata)
      Retrieves the WebSocket session ID from the provided metadata, or null if it is missing.

    • requireSocketSessionId

      public static String requireSocketSessionId(Metadata metadata)
      Retrieves the WebSocket session ID from the provided metadata or throws an exception if it is missing.