Package dev.relism.flash.models

Class Request

java.lang.Object
dev.relism.flash.models.Request
public class Request extends Object
View of an incoming HTTP/1.1 request. Constructed once per connection by RequestParser and repositioned (never reallocated) for every request on that connection — never modified by user code after creation (path/query params are injected once by the router before the handler runs). 

 server.get("/users/{id}", (req, res) -> {
     String id      = req.param("id");            // /users/42 → "42"
     String page    = req.query("page");           // ?page=2   → "2"
     String accept  = req.header("Accept");        // first Accept value
     byte[] body    = req.body().bytes();          // materialise body
     InputStream in = req.body().stream();         // zero-copy stream
 });
A Request instance is owned by its connection (HTTP/1.1) or its stream (HTTP/2) and is recycled after the handler returns. Do not retain it — the same instance is repositioned over the next request's data as soon as this one's handler returns. equals/ hashCode are the inherited identity-based Object versions and are meaningless across requests (compare two different Requests from the same connection and they may be == to each other despite describing entirely different requests, at different points in time). String values returned by path(), header(String), param(String), query(String) are independent heap copies and are always safe to retain past the handler.

Dev-mode use-after-recycle guard

When Flash.DEV is true, every accessor checks that this instance is still the one currently being handled; a call after the handler has already returned (e.g. from a captured reference in an async callback, a CompletableFuture continuation, or a background thread) throws IllegalStateException immediately, loudly, and at the exact call site that misused it — instead of silently reading whatever the next (or a completely different) request happened to reset this instance to. In production this check is a single boolean field read gated behind a static final flag the the measured cost.

  • Constructor Details

    • Request

      public Request()
      Pooled instance, populated later via reset(dev.relism.flash.models.RequestLine, dev.relism.flash.models.RequestBody, java.net.InetSocketAddress, javax.net.ssl.SSLSocket). One per connection — see RequestParser.

    • Request

      public Request(RequestLine requestLine, byte[] body)
      Test / manual constructor — remoteAddress() returns null, isSecure() is false.

  • Method Details

    • recycle

      public void recycle()
      Marks this instance unsafe for further use. Called by the connection driver (e.g. Http1Connection) once the handler (and any automatic post-handler work, e.g. drain()) has finished with it, before the connection loop reuses it for the next request — public because the connection driver lives in a different package (matching RequestLine.reset(dev.relism.flash.http.HttpMethod, dev.relism.fpr.core.ByteView, dev.relism.fpr.core.ByteView, dev.relism.fpr.core.ByteView, dev.relism.flash.models.HeaderView)'s own precedent), not because user code should ever call it. A no-op in production beyond the field write — see the class Javadoc's dev-mode guard section.

    • forParsed

      public static Request forParsed(Request pooled, RequestLine requestLine, RequestBody body, InetSocketAddress remoteAddress, SSLSocket sslSocket)
      Repositions pooled over a freshly-parsed request. body is already fully configured by the caller (RequestParser, which owns and resets its own pooled method's only job is wiring it, requestLine, and the connection identity fields into pooled.

    • setTrailers

      public void setTrailers(HeaderView trailers)
      Internal protocol hook that supplies the request's trailer collection.

    • method

      public HttpMethod method()
      HTTP method (GET, POST, …).

    • path

      public String path()
      Request path decoded as UTF-8. Includes a leading slash; never includes the query string. Example: a request for /users/42?page=1 returns "/users/42".

    • header

      public String header(String name)
      Returns the first value of header name, or null if absent. Lookup is case-insensitive ("content-type" and "Content-Type" are equivalent).

    • headers

      public List<String> headers(String name)
      Returns all values of header name in declaration order. Useful for headers that appear multiple times (e.g. Accept, Cookie). Lookup is case-insensitive. Returns an empty list if the header is absent.

    • headers

      public List<String> headers()
      Returns all header values in declaration order, one entry per header line. Useful for debugging; for targeted access prefer header(String).

    • origin

      public String origin()
      The scheme and authority the client addressed, e.g. https://example.com: the connection's scheme and the Host header. The client chooses both, so nothing that must not be misled reads this alone; it reads an origin the application configured, falling back to this one.

    • cookie

      public String cookie(String name)
      Returns the value of cookie name, or null if the request does not carry it. Reads the Cookie header in place; only the returned value is allocated.

    • param

      public String param(String name)
      Returns the path parameter named name, or null. Parameters are declared in the route pattern (e.g. /users/{id}) and injected by the router before the handler runs. Returns null if this route has no such parameter or the route is not parametric.

    • query

      public String query(String name)
      Returns the first query parameter named name, or null. The query string is parsed lazily on the first call and cached for the request lifetime. For ?a=1&a=2, returns "1".

    • queries

      public List<String> queries(String name)
      Returns all query parameters named name in declaration order. For ?tag=a&tag=b, returns ["a", "b"]. Returns an empty list if the parameter is absent.

    • remoteAddress

      public InetSocketAddress remoteAddress()
      Returns the remote socket address of the connected client, or null for test-constructed requests.

      The InetSocketAddress is the JDK object created during ServerSocket.accept() — no allocation occurs here. To obtain the IP string (lazy, allocates once): 

      
 InetSocketAddress addr = req.remoteAddress();
 if (addr != null) String ip = addr.getAddress().getHostAddress();

    • isSecure

      public boolean isSecure()
      Whether this request arrived over TLS (HTTPS).

    • sslSession

      public SSLSession sslSession()
      Returns the TLS session for this connection, or null for plain HTTP. Gives access to SSLSession.getPeerCertificates() (mTLS — the caller's certificate chain, if TlsConfig.clientAuth required or requested one), and to SSLSession.getCipherSuite() / SSLSession.getProtocol() for logging and diagnostics. null rather than throwing when isSecure() is false — check that first, or just null-check the result.

    • body

      public RequestBody body()
      Returns the request body accessor. Use RequestBody.bytes() to materialise the full body or RequestBody.stream() for zero-copy streaming access. The two modes are mutually exclusive per request.

    • trailers

      public HeaderView trailers()
      Returns request trailers after the body has been consumed completely.
      Throws:
      IllegalStateException - when called before the body reaches EOF

    • drain

      public void drain()
      Discards unread body bytes; called by the server after each request on keep-alive connections.

    • getRequestLine

      public RequestLine getRequestLine()
      Internal: the parsed request line (method, path, query, protocol, headers).

    • getPathParams

      public PathParams getPathParams()
      Internal: path parameters injected by the router, or null if none matched.

    • headerEquals

      public boolean headerEquals(String name, String value)
      Internal: case-insensitive header value comparison used by the server keep-alive logic.

    • toString

      public String toString()
      Overrides:
      toString in class Object