@spec append_response_header(t(), String.t(), String.t()) :: t()

Appends a value to a response header, keeping any existing value.

The header name is downcased. If the header already has a value, the new value is appended after a comma. Use put_response_header/3 to replace instead of append.

Parameters

• server - The server struct
• name - The header name (string)
• value - The header value to append (string)

@spec delete_cookie(t(), String.t()) :: t()

Removes a cookie from the server struct and marks it for deletion in the client's browser.

If the cookie exists, it is removed from the server struct's cookies data and a delete operation is recorded in the metadata. If the cookie does not exist, this function is a no-op and returns the server struct unchanged.

Parameters

• server - The server struct
• key - The cookie name to delete (must be a string)

Examples

iex> server = %Hologram.Server{cookies: %{"user_id" => "123", "theme" => "dark"}}
iex> delete_cookie(server, "user_id")
%Hologram.Server{cookies: %{"theme" => "dark"}}

iex> # Deleting a nonexistent cookie is a no-op
iex> server = %Hologram.Server{cookies: %{"theme" => "dark"}}
iex> delete_cookie(server, "nonexistent")
%Hologram.Server{cookies: %{"theme" => "dark"}}

iex> server = %Hologram.Server{}
iex> delete_cookie(server, "any_key")
%Hologram.Server{cookies: %{}}

@spec delete_response_header(t(), String.t()) :: t()

Removes a response header from the server struct so it will not be sent.

The header name is downcased to match how headers are stored. Removing a header that is not present is a no-op.

Parameters

• server - The server struct
• name - The header name (string)

@spec delete_session(t(), atom() | String.t()) :: t()

Removes a session entry from the server struct and marks it for deletion in the client's browser.

If the session entry exists, it is removed from the server struct's session data and a delete operation is recorded in the metadata. If the session entry does not exist, this function is a no-op and returns the server struct unchanged.

Atom keys are automatically converted to string.

Parameters

• server - The server struct
• key - The session entry name to delete (atom or string)

@spec delete_stash(t(), atom()) :: t()

Removes a key from the request-scoped stash.

Removing a key that is not present is a no-op.

Parameters

• server - The server struct
• key - The stash key (atom)

@spec delete_user_id(t()) :: t()

Clears the authenticated user identity on the server struct.

Sets user_id to nil. The change is persisted to the session (removing the identity) when the server struct is applied.

Parameters

• server - The server struct

@spec from(Plug.Conn.t()) :: t()

Creates a new Hologram.Server struct from a Plug.Conn struct.

Populates the request fields (method, scheme, host, port, path, query, raw_query, ip, request_headers) and the identity fields. The cookie request header is dropped from request_headers since cookies are exposed via the cookie functions, and a request header sent multiple times is comma-joined.

Excludes "hologram_session" cookie. Populates session_id and user_id from the Phoenix session (each nil when the underlying entry is absent), and strips those Hologram-managed keys from the session map so it contains only application-level entries.

@spec get_cookie(t(), String.t(), any()) :: any()

Retrieves a cookie value by key from the server struct.

Returns the value associated with the given key or the default value if the key does not exist in the cookies.

Parameters

• server - The server struct
• key - The cookie name (string)
• default - The value to return if the key is not found (default: nil)

Examples

iex> server = %Hologram.Server{cookies: %{"user_id" => "abc123"}}
iex> get_cookie(server, "user_id")
"abc123"

iex> server = %Hologram.Server{cookies: %{"user_id" => "abc123"}}
iex> get_cookie(server, "nonexistent")
nil

iex> server = %Hologram.Server{cookies: %{"user_id" => "abc123"}}
iex> get_cookie(server, "nonexistent", "default_value")
"default_value"

@spec get_cookie_ops(t()) :: %{required(String.t()) => Hologram.Runtime.Cookie.op()}

Retrieves the cookie operations recorded in the server struct's metadata.

@spec get_request_header(t(), String.t(), any()) :: any()

Retrieves a request header value by name from the server struct.

The header name is downcased to match how request headers are stored. Returns the value associated with the name, or the default if the header is not present.

Parameters

• server - The server struct
• name - The header name (string)
• default - The value to return if the header is not present (default: nil)

@spec get_response_header(t(), String.t(), any()) :: any()

Retrieves a response header value by name from the server struct.

The header name is downcased to match how response headers are stored. Returns the value associated with the name, or the default if the header is not present.

Parameters

• server - The server struct
• name - The header name (string)
• default - The value to return if the header is not present (default: nil)

@spec get_session(t(), atom() | String.t(), any()) :: any()

Retrieves a session value by key from the server struct.

Returns the value associated with the given key or the default value if the key does not exist in the cookies.

Atom keys are automatically converted to string.

Parameters

• server - The server struct
• key - The session entry name (atom or string)
• default - The value to return if the key is not found (default: nil)

@spec get_session_ops(t()) :: %{required(String.t()) => Hologram.Runtime.Session.op()}

Retrieves the session operations recorded in the server struct's metadata.

@spec get_stash(t(), atom(), any()) :: any()

Retrieves a value from the request-scoped stash by key.

Returns the value associated with the key, or the default if the key is not present.

Parameters

• server - The server struct
• key - The stash key (atom)
• default - The value to return if the key is not present (default: nil)

@spec has_cookie_ops?(t()) :: boolean()

Checks if the server struct has any recorded cookie operations.

Returns true if there are any cookie operations (put or delete) in the server structs's metadata, false otherwise.

Parameters

• server - The server struct

Examples

iex> server = %Hologram.Server{}
iex> has_cookie_ops?(server)
false

iex> server = %Hologram.Server{cookies: %{"user_id" => "123"}}
iex> server = put_cookie(server, "theme", "dark")
iex> has_cookie_ops?(server)
true

@spec put_cookie(t(), String.t(), any(), keyword()) :: t()

Adds a cookie to be set in the client's browser.

Parameters

• server - The server struct
• key - The cookie name (must be a string)
• value - The cookie value
• opts - Optional cookie attributes (keyword list)

Options

• :domain - The domain for the cookie (default: nil)
• :http_only - Whether the cookie should be accessible only through HTTP(S) requests (default: true)
• :max_age - Maximum age in seconds (default: nil)
• :path - The path for the cookie (default: nil)
• :same_site - SameSite attribute (default: :lax)
• :secure - Whether the cookie should only be sent over HTTPS (default: true)

Examples

iex> server = %Hologram.Server{}
iex> put_cookie(server, "user_id", 123)
%Hologram.Server{cookies: %{"user_id" => 123}}

iex> server = %Hologram.Server{}
iex> put_cookie(server, "theme", "dark", secure: false, path: "/admin")
%Hologram.Server{cookies: %{"theme" => "dark"}}

@spec put_redirect(t(), String.t() | module()) :: t()

Sets a temporary (302) redirect to the given target, marking the response as terminal.

The target is either a URL string, used as-is, or a page module, resolved to its path. For a page with params, use put_redirect/3. For a different status code, follow with put_status/2.

Parameters

• server - The server struct
• target - A URL string or a page module

@spec put_redirect(t(), module(), keyword() | map()) :: t()

Sets a temporary (302) redirect to the given page module with params, marking the response as terminal.

For a different status code, follow with put_status/2.

Parameters

• server - The server struct
• page_module - The target page module
• params - Page params (keyword list or map)

@spec put_response_body(t(), iodata()) :: t()

Sets a custom response body to be sent to the client.

The body is iodata (a binary or an iolist). Combine with put_status/2 to build a custom response (the status is what marks the response as terminal and skips the handler).

Parameters

• server - The server struct
• body - The response body (iodata)

@spec put_response_header(t(), String.t(), String.t()) :: t()

Sets a response header to be sent to the client, replacing any existing value for the name.

The header name is downcased, so names are case-insensitive and a later put overwrites an earlier one regardless of case.

Parameters

• server - The server struct
• name - The header name (string)
• value - The header value (string)

@spec put_session(t(), atom() | String.t(), any()) :: t()

Adds a session entry.

Session keys are stored as strings (atom keys are converted to strings). In embedded mode the session is backed by the Phoenix session store, which uses string keys, and recovering atom keys would require an unsafe string-to-atom conversion.

Parameters

• server - The server struct
• key - The session entry name (atom or string)
• value - The session entry value

@spec put_stash(t(), atom(), any()) :: t()

Stores a value in the request-scoped stash under an atom key.

The stash is ephemeral, in-memory request state for passing data between middleware steps and into the handler. It is never persisted or sent to the client.

Parameters

• server - The server struct
• key - The stash key (atom)
• value - The value to store

@spec put_status(t(), pos_integer() | atom()) :: t()

Sets the response status, marking the response as terminal so the handler is skipped.

Accepts an integer status code in the 100..599 range (e.g. 403) or an atom alias (e.g. :forbidden), which is resolved to its numeric code. Raises for an unknown alias or an out-of-range code.

Parameters

• server - The server struct
• status - The response status (integer code or atom alias)

Examples

iex> server = %Hologram.Server{}
iex> put_status(server, 404)
%Hologram.Server{status: 404}

iex> server = %Hologram.Server{}
iex> put_status(server, :not_found)
%Hologram.Server{status: 404}

@spec put_user_id(t(), identity_id()) :: t()

Sets the authenticated user identity on the server struct.

The change is persisted to the session when the server struct is applied. Use delete_user_id/1 to clear the identity.

Parameters

• server - The server struct
• user_id - The user identity (a string, integer, or atom)

@spec referrer_url(t()) :: String.t() | nil

Returns the request's referrer URL, or nil when absent.

Reads the Referer request header. The HTTP spec famously misspelled "referrer" as "Referer", and the header has carried the typo ever since - so this helper takes the correct spelling and reads the misspelled header under the hood.

@spec request_url(t()) :: String.t()

Returns the full request URL, assembled from the request fields.

The scheme's default port (80 for :http, 443 for :https) is omitted, and the query string is appended only when present.