zyn.Response#

/// An owned deferred outcome. Value constructors copy body and metadata using
/// the process allocator; prefer request-role helpers for request-arena storage.
/// Return or respond with the value to transfer it, or call deinit exactly once.
pub const Response = union(enum) {
    complete,

    /// Options shared by complete-body response helpers.
    pub const Options = struct {
        status: std.http.Status = .ok,
        etag: ?EntityTag = null,
        /// Unix timestamp in microseconds used for Last-Modified.
        last_modified: ?i64 = null,
    };

    /// Options for a complete byte response.
    pub const BytesOptions = struct {
        status: std.http.Status = .ok,
        etag: ?EntityTag = null,
        /// Unix timestamp in microseconds used for Last-Modified.
        last_modified: ?i64 = null,
        content_type: []const u8 = "application/octet-stream",
    };

    /// Options for an incremental buffered response.
    pub const WriterOptions = struct {
        status: std.http.Status = .ok,
        etag: ?EntityTag = null,
        /// Unix timestamp in microseconds used for Last-Modified.
        last_modified: ?i64 = null,
        content_type: ?[]const u8 = null,
    };

    /// An authentication scheme supported by the typed challenge response.
    pub const ChallengeScheme = enum {
        basic,
        bearer,
    };

    /// Parameters for a Basic authentication challenge.
    pub const BasicChallengeOptions = struct {
        realm: []const u8,
        charset: ?Charset = null,

        /// The Basic challenge character encoding.
        pub const Charset = enum {
            utf8,
        };
    };

    /// Parameters for a Bearer authentication challenge.
    pub const BearerChallengeOptions = struct {
        realm: ?[]const u8 = null,
        scope: ?[]const u8 = null,
        error_code: ?ErrorCode = null,
        error_description: ?[]const u8 = null,
        error_uri: ?[]const u8 = null,

        /// A standard Bearer authentication error code.
        pub const ErrorCode = enum {
            invalid_request,
            invalid_token,
            insufficient_scope,
        };
    };

    /// Returns an empty complete response.
    /// Prefer `.empty(...)` when the expected type is `Response`.
    pub fn empty(options: Options) std.mem.Allocator.Error!Response;

    /// Returns a plain-text complete response.
    /// Prefer `.text(...)` when the expected type is `Response`.
    pub fn text(value: []const u8, options: Options) std.mem.Allocator.Error!Response;

    /// Returns an HTML complete response.
    /// Prefer `.html(...)` when the expected type is `Response`.
    pub fn html(value: []const u8, options: Options) std.mem.Allocator.Error!Response;

    /// Returns an XML complete response.
    /// Prefer `.xml(...)` when the expected type is `Response`.
    pub fn xml(value: []const u8, options: Options) std.mem.Allocator.Error!Response;

    /// Returns a Markdown complete response.
    /// Prefer `.markdown(...)` when the expected type is `Response`.
    pub fn markdown(value: []const u8, options: Options) std.mem.Allocator.Error!Response;

    /// Returns an iCalendar complete response.
    /// Prefer `.ics(...)` when the expected type is `Response`.
    pub fn ics(value: []const u8, options: Options) std.mem.Allocator.Error!Response;

    /// Returns a CSV complete response.
    pub fn csv(value: []const u8, options: Options) std.mem.Allocator.Error!Response;

    /// Returns an SVG complete response.
    pub fn svg(value: []const u8, options: Options) std.mem.Allocator.Error!Response;

    /// Returns a complete byte response, defaulting to application/octet-stream.
    pub fn bytes(
        value: []const u8,
        options: BytesOptions,
    ) std.mem.Allocator.Error!Response;

    /// Returns an empty redirect response.
    /// Prefer `.redirect(...)` when the expected type is `Response`.
    pub fn redirect(
        status: std.http.Status,
        location: []const u8,
    ) std.mem.Allocator.Error!Response;

    /// Returns a terminal 401 response with a typed authentication challenge.
    /// Prefer `.challenge(...)` when the expected type is `Response`.
    pub fn challenge(
        comptime scheme: ChallengeScheme,
        options: switch (scheme) {
            .basic => BasicChallengeOptions,
            .bearer => BearerChallengeOptions,
        },
    ) std.mem.Allocator.Error!Response;

    /// Releases an outcome that is not transferred to the framework.
    pub fn deinit(self: *Response) void;
};