zyn.http.Request#
/// The live request being handled.
pub const Request = struct {
/// A framework-generated 128-bit identifier encoded as lowercase hexadecimal.
request_id: Id,
locals: *app.Locals,
session: app.Session,
io: std.Io,
arena: std.mem.Allocator,
middlewares: @FieldType(httpz.Request, "middlewares"),
method: @FieldType(httpz.Request, "method"),
method_string: []const u8,
url: @FieldType(httpz.Request, "url"),
/// The parsed inbound Content-Type field, or `null` when absent.
content_type: ?MediaType,
pub const Id = []const u8;
pub const MediaType = media_type_module.MediaType;
/// A recognized response format or an application-defined format name.
pub const Format = union(enum) {
html,
json,
markdown,
xml,
ics,
other: []const u8,
/// Classifies a format name, canonicalizing recognized aliases.
pub fn from_name(value: []const u8) Format;
/// Returns the canonical format name.
pub fn name(self: Format) []const u8;
};
/// Ordered response formats acceptable to a request.
pub const Formats = struct {
values: [known.len]Format = undefined,
len: usize = 0,
/// Returns the populated response-format slice.
pub fn slice(self: *const Formats) []const Format;
};
/// A parsed HTTP Authorization field.
pub const Authorization = union(enum) {
missing,
invalid,
basic: Basic,
bearer: []const u8,
other: Other,
/// Decoded Basic credentials.
pub const Basic = struct {
username: []const u8,
password: []const u8,
};
/// An application-defined authorization scheme and its uninterpreted credentials.
pub const Other = struct {
scheme: []const u8,
credentials: []const u8,
};
};
/// The maximum number of typed payload validation details retained per request.
pub const max_invalid_payload_details = 16;
/// The maximum byte length of one typed payload validation path.
pub const max_invalid_payload_path_length = 256;
/// The maximum byte length of one typed payload validation reason.
pub const max_invalid_payload_reason_length = 64;
/// The maximum byte length of one typed payload expected or actual description.
pub const max_invalid_payload_description_length = 128;
/// Read-only inbound request headers.
pub const RequestHeaders = struct {
/// Returns the combined inbound request field matching `name`.
pub fn get(self: RequestHeaders, name: []const u8) ?[]const u8;
};
/// Errors returned by an application-owned payload parser.
pub const PayloadError = error{
OutOfMemory,
InvalidRequestPayload,
};
/// Request-scoped input supplied to an application-owned payload parser.
pub const Payload = struct {
arena: std.mem.Allocator,
body: []const u8,
/// The parsed inbound Content-Type field, or `null` when absent.
content_type: ?MediaType,
headers: RequestHeaders,
/// One typed payload validation issue.
pub const Detail = struct {
path: []const u8,
reason: []const u8,
expected: ?[]const u8 = null,
actual: ?[]const u8 = null,
};
/// Adds one validation issue. The framework rejects the parsed value after
/// the parser returns when any issues were added.
pub fn invalidate(
self: *Payload,
detail: Detail,
) error{OutOfMemory}!void;
};
/// One typed payload validation issue.
pub const InvalidPayloadDetail = Payload.Detail;
/// Bounded typed payload validation issues and truncation state.
pub const InvalidPayloadDetails = struct {
items: []const InvalidPayloadDetail,
truncated: bool,
};
/// Immutable parsed request query fields.
pub const QueryParameters = struct {
names: []const []const u8,
field_values: []const []const u8,
/// One query field.
pub const Entry = struct {
key: []const u8,
value: []const u8,
};
/// Every query field in wire order.
pub const Iterator = struct {
query: QueryParameters,
index: usize = 0,
/// Returns the next query field.
pub fn next(self: *Iterator) ?Entry;
};
/// Values for one repeated query name in wire order.
pub const Values = struct {
query: QueryParameters,
name: []const u8,
index: usize = 0,
/// Returns the next value matching the selected query name.
pub fn next(self: *Values) ?[]const u8;
};
/// Returns the first value matching `name`.
pub fn get(self: QueryParameters, name: []const u8) ?[]const u8;
/// Returns every value matching `name` in wire order.
pub fn values(self: QueryParameters, name: []const u8) Values;
/// Returns every query field in wire order.
pub fn iterator(self: QueryParameters) Iterator;
};
/// Returns the raw request body when one is present.
pub fn body(self: *const Request) ?[]const u8;
/// Returns the combined header value whose name matches case-insensitively.
pub fn header(self: *const Request, name: []const u8) ?[]const u8;
/// Returns response formats acceptable to the request in preference order.
pub fn formats(self: *const Request) Formats;
/// Parses the unique Authorization field using request-scoped storage.
///
/// Missing and malformed fields return tagged states. Allocation failure while
/// decoding Basic credentials is propagated.
///
/// Basic credentials are decoded as UTF-8, Bearer credentials remain opaque,
/// and unrecognized schemes retain their uninterpreted credential bytes.
pub fn authorization(self: *Request) std.mem.Allocator.Error!Authorization;
/// Returns a decoded declared matched-route parameter, or `null` when absent.
pub fn param(self: *const Request, key: []const u8) ?[]const u8;
/// Parses and returns immutable request query fields. Lookup returns the first
/// value for a repeated name; filtered and complete iteration retain wire order.
pub fn query(self: *Request) !QueryParameters;
/// Returns a request cookie jar using the request arena and validated
/// 64-character lowercase hexadecimal `ZYN_KEY` material.
pub fn cookies(self: *Request) Cookies;
/// Requires a payload matching `T`. A type-owned `parse` declaration receives
/// the raw body; other types are decoded strictly from JSON objects or forms.
pub fn expect_payload(self: *Request, comptime T: type) !T;
/// Returns bounded details from the most recent failed `expect_payload` call,
/// or `null` when that failure was not caused by typed validation.
pub fn invalid_payload_details(self: *const Request) ?InvalidPayloadDetails;
/// Returns the decoded body payload. JSON objects and URL-encoded forms are
/// normalized to a JSON object map; path and query parameters are excluded.
pub fn payload(self: *Request) !?std.json.ObjectMap;
pub const Cookies = struct {
signed: Protected,
encrypted: Protected,
/// Creates a standalone request cookie jar with explicit key material.
pub fn init(
header_value: []const u8,
allocator: std.mem.Allocator,
key_material: []const u8,
) Cookies;
/// Returns a plain cookie value, or `null` when unavailable.
pub fn get(self: Cookies, key: []const u8) !?[]const u8;
/// A signed or encrypted request-cookie capability.
pub const Protected = struct {
/// Returns a verified or decrypted cookie value, or `null` when unavailable.
pub fn get(self: Protected, key: []const u8) !?[]const u8;
};
};
};