zyn.http.Response#
/// The live mutable response being prepared.
pub const Response = struct {
status: u16,
content_type: ?httpz.ContentType,
body: []const u8,
/// Errors returned when owning or adding an application response header.
pub const HeaderError = std.mem.Allocator.Error || error{
InvalidHeaderName,
InvalidHeaderValue,
ResponseHeadersFull,
};
/// Errors returned when preparing an authentication challenge.
pub const ChallengeError = HeaderError || error{InvalidChallenge};
/// Errors returned while applying response options.
pub const OptionsError = HeaderError || error{
InvalidEntityTag,
InvalidHttpDate,
ResponseBodyTooLarge,
};
/// 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,
};
};
/// The response operations which can commit bytes to the client are guarded
/// until CSRF validation and every route guard have allowed the request.
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;
};
/// Renders an HTML or XML view with configured layouts of the same format.
pub fn render(
self: *Response,
template_name: []const u8,
params: anytype,
options: Options,
) !void;
/// Serializes a value as JSON with complete-response options.
pub fn json(
self: *Response,
value: anytype,
options: Options,
) !void;
/// Sets an empty complete response.
pub fn empty(self: *Response, options: Options) OptionsError!void;
/// Sets a plain-text body with complete-response options.
pub fn text(self: *Response, body: []const u8, options: Options) OptionsError!void;
/// Sets an XML body with complete-response options.
pub fn xml(self: *Response, body: []const u8, options: Options) OptionsError!void;
/// Sets a Markdown body with complete-response options.
pub fn markdown(self: *Response, body: []const u8, options: Options) OptionsError!void;
/// Sets an iCalendar body with complete-response options.
pub fn ics(self: *Response, body: []const u8, options: Options) OptionsError!void;
/// Sets a CSV body with complete-response options.
pub fn csv(self: *Response, body: []const u8, options: Options) OptionsError!void;
/// Sets an SVG body with complete-response options.
pub fn svg(self: *Response, body: []const u8, options: Options) OptionsError!void;
/// Sets a byte body, defaulting to application/octet-stream.
pub fn bytes(self: *Response, body: []const u8, options: BytesOptions) OptionsError!void;
/// Sets an HTML body with complete-response options.
pub fn html(self: *Response, body: []const u8, options: Options) OptionsError!void;
/// Sets a terminal 401 response with a typed WWW-Authenticate challenge.
pub fn challenge(
self: *Response,
comptime scheme: ChallengeScheme,
options: switch (scheme) {
.basic => BasicChallengeOptions,
.bearer => BearerChallengeOptions,
},
) ChallengeError!void;
/// Sets an empty redirect response with the supplied HTTP status and location.
pub fn redirect(
self: *Response,
status: std.http.Status,
location: []const u8,
) HeaderError!void;
/// Sets or case-insensitively replaces an owned response header.
pub fn header(
self: *Response,
name: []const u8,
value: []const u8,
) HeaderError!void;
/// Removes a response header case-insensitively.
pub fn remove_header(self: *Response, name: []const u8) void;
/// Applies request preconditions to the current selected representation.
/// Returns whether a canonical 304 or 412 response was prepared.
pub fn apply_preconditions(
self: *Response,
current: ?Validators,
) OptionsError!bool;
/// Returns the buffered response writer, or `null` when request preconditions
/// have already completed the response as 304 or 412.
pub fn writer(self: *Response, options: WriterOptions) OptionsError!?*Io.Writer;
/// Returns a response cookie jar using validated 64-character lowercase
/// hexadecimal `ZYN_KEY` material.
pub fn cookies(self: *Response) Cookies;
pub const Cookies = struct {
pub const Lifetime = cookie.Lifetime;
pub const SameSite = cookie.SameSite;
pub const SetOptions = cookie.SetOptions;
pub const DeleteOptions = cookie.DeleteOptions;
/// Creates a standalone response cookie jar with explicit key material.
pub fn init(response: *httpz.Response, key_material: []const u8) !Cookies;
/// Returns a jar that signs values and emits protected-cookie attributes.
pub fn signed(self: Cookies) Cookies;
/// Returns a jar that encrypts values and emits protected-cookie attributes.
pub fn encrypted(self: Cookies) Cookies;
/// Appends an encoded response cookie with the supplied attributes.
pub fn set(
self: Cookies,
key: []const u8,
value: []const u8,
options: SetOptions,
) !void;
/// Appends an immediately expired response cookie with the supplied scope.
pub fn delete(self: Cookies, key: []const u8, options: DeleteOptions) !void;
};
};