zyn.Hook#

/// The request-scoped API passed to route hooks.
pub const Hook = struct {
    auth: *auth_api.Request = &auth_api.disabled,
    db: Database,
    cache: Cache = .{},
    jobs: Jobs,
    notifications: Notifications,
    storage: Storage,
    logger: *const Logger,
    /// The framework-generated request identifier.
    request_id: Request.Id,
    headers: Headers,
    cookies: Cookies,
    locals: @FieldType(Request, "locals"),
    session: *@FieldType(Request, "session"),
    io: std.Io,
    arena: std.mem.Allocator,
    method: @FieldType(Request, "method"),
    method_string: []const u8,
    url: @FieldType(Request, "url"),
    /// The parsed inbound Content-Type field, or `null` when absent.
    content_type: ?MediaType,
    /// Response formats acceptable to the request in preference order.
    formats: []const Request.Format,

    pub const Format = Request.Format;
    pub const Authorization = Request.Authorization;
    pub const QueryParameters = Request.QueryParameters;
    pub const InvalidPayloadDetail = Request.InvalidPayloadDetail;
    pub const InvalidPayloadDetails = Request.InvalidPayloadDetails;
    pub const Raw = Action.Raw;

    /// Copies a plain-text response into request memory and returns its outcome.
    pub fn text(self: *Hook, body_bytes: []const u8, options: Response.Options) !Response;

    /// Copies a HTML response into request memory and returns its outcome.
    pub fn html(self: *Hook, body_bytes: []const u8, options: Response.Options) !Response;

    /// Copies a XML response into request memory and returns its outcome.
    pub fn xml(self: *Hook, body_bytes: []const u8, options: Response.Options) !Response;

    /// Copies a Markdown response into request memory and returns its outcome.
    pub fn markdown(self: *Hook, body_bytes: []const u8, options: Response.Options) !Response;

    /// Copies a iCalendar response into request memory and returns its outcome.
    pub fn ics(self: *Hook, body_bytes: []const u8, options: Response.Options) !Response;

    /// Copies a CSV response into request memory and returns its outcome.
    pub fn csv(self: *Hook, body_bytes: []const u8, options: Response.Options) !Response;

    /// Copies a SVG response into request memory and returns its outcome.
    pub fn svg(self: *Hook, body_bytes: []const u8, options: Response.Options) !Response;

    /// Copies a byte response and its metadata into request memory.
    pub fn bytes(self: *Hook, body_bytes: []const u8, options: Response.BytesOptions) !Response;

    /// Prepares an empty response using request-owned metadata.
    pub fn empty(self: *Hook, options: Response.Options) !Response;

    /// Copies the redirect location into request memory.
    pub fn redirect(self: *Hook, status: std.http.Status, location: []const u8) !Response;

    /// Copies an authentication challenge into request memory.
    pub fn challenge(
        self: *Hook,
        comptime scheme: Response.ChallengeScheme,
        options: switch (scheme) {
            .basic => Response.BasicChallengeOptions,
            .bearer => Response.BearerChallengeOptions,
        },
    ) !Response;

    /// Returns the raw request body when one is present.
    pub fn body(self: *const Hook) ?[]const u8;

    /// Parses the unique Authorization request field.
    pub fn authorization(self: *Hook) !Authorization;

    /// Returns a decoded matched-route parameter.
    pub fn param(self: *const Hook, key: []const u8) []const u8;

    /// Parses and returns the request query fields.
    pub fn query(self: *Hook) !QueryParameters;

    /// Requires a decoded request payload matching `T`.
    pub fn expect_payload(self: *Hook, comptime T: type) !T;

    /// Returns details from the most recent typed payload failure.
    pub fn invalid_payload_details(self: *const Hook) ?InvalidPayloadDetails;

    /// Returns the decoded request body payload.
    pub fn payload(self: *Hook) !?std.json.ObjectMap;

    /// Renders a view and returns its completed response.
    pub fn render(
        self: *Hook,
        comptime template_name: []const u8,
        params: anytype,
        options: Response.Options,
    ) !Response;

    /// Serializes a value as JSON and returns its completed response.
    pub fn json(self: *Hook, value: anytype, options: Response.Options) !Response;

    /// Returns the buffered response writer, or `null` after a terminal precondition.
    pub fn writer(self: *Hook, options: Response.WriterOptions) !?*std.Io.Writer;

    /// Returns guarded immediate response operations.
    pub fn raw(self: *Hook) *Raw;

    /// Continues the downstream pipeline.
    pub fn next(self: *Hook) !void;

    /// Applies a response without continuing the downstream pipeline.
    pub fn respond(self: *Hook, response: Response) !void;
};