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 will be forwarded by the proxy in Fluxzero Runtime.

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 a cookie by name.
      Parameters:
      name - the cookie name
      Returns:
      optional cookie

    • 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-sensitive 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

    • 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.