zyn.Action#

/// The request-scoped API passed to a route action.
pub const Action = 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,
    flash: Flash,
    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;
    /// Guarded immediate response operations.
    pub const Raw = struct {
        /// Commits headers on the first call and writes one chunk immediately.
        pub fn chunk(self: *Raw, data: []const u8) !void;

        /// Transfers response ownership and all later cleanup to the application.
        pub fn disown(self: *Raw) !void;

        /// Commits and disowns an event stream, then runs its owner on a detached thread.
        pub fn start_event_stream(
            self: *Raw,
            context: anytype,
            comptime handler: fn (@TypeOf(context), std.Io.net.Stream) void,
        ) !void;

        /// Commits and disowns an event stream, returning its application-owned stream.
        pub fn start_event_stream_sync(self: *Raw) !std.Io.net.Stream;

        /// Commits response headers without completing or transferring the response.
        pub fn write_header(self: *Raw) !void;

        /// Commits and completes the response, or terminates an active chunked response.
        pub fn write(self: *Raw) !void;
    };

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

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

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

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

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

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

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

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

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

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

    /// Copies an authentication challenge into request memory.
    pub fn challenge(
        self: *Action,
        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 Action) ?[]const u8;

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

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

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

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

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

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

    /// Renders a view and returns its completed response.
    pub fn render(
        self: *Action,
        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: *Action, value: anytype, options: Response.Options) !Response;

    /// Applies request preconditions to the current selected representation.
    /// Returns a completed 304 or 412 response, or null to continue.
    pub fn apply_preconditions(
        self: *Action,
        current: ?Validators,
    ) !?Response;

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

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