zyn.Cookies#

/// The combined request and response cookie jar used by response-capable request roles.
pub const Cookies = struct {
    signed: Protected,
    encrypted: Protected,

    /// How long a written cookie remains eligible for storage.
    pub const Lifetime = union(enum) {
        session,
        permanent,
        max_age_seconds: i64,
    };

    /// A cookie's cross-site delivery policy.
    pub const SameSite = enum {
        lax,
        strict,
        none,
    };

    /// Attributes applied when writing a cookie.
    pub const SetOptions = struct {
        lifetime: Lifetime = .session,
        path: []const u8 = "/",
        domain: ?[]const u8 = null,
        secure: ?bool = null,
        http_only: ?bool = null,
        same_site: ?SameSite = .lax,
    };

    /// Scope and transport attributes applied when deleting a cookie.
    pub const DeleteOptions = struct {
        path: []const u8 = "/",
        domain: ?[]const u8 = null,
        secure: ?bool = null,
    };

    /// Returns a plain request cookie value, or `null` when unavailable.
    pub fn get(self: Cookies, key: []const u8) !?[]const u8;

    /// Appends a plain response cookie with the supplied attributes.
    pub fn set(
        self: Cookies,
        key: []const u8,
        value: []const u8,
        options: SetOptions,
    ) !void;

    /// Expires a plain response cookie with the supplied scope.
    pub fn delete(self: Cookies, key: []const u8, options: DeleteOptions) !void;

    /// A signed or encrypted request and response cookie capability.
    pub const Protected = struct {
        /// Returns a verified or decrypted cookie value, or `null` when unavailable.
        pub fn get(self: Cookies.Protected, key: []const u8) !?[]const u8;

        /// Appends an encoded response cookie with the supplied attributes.
        pub fn set(
            self: Protected,
            key: []const u8,
            value: []const u8,
            options: SetOptions,
        ) !void;

        /// Expires a protected response cookie with the supplied scope.
        pub fn delete(
            self: Protected,
            key: []const u8,
            options: DeleteOptions,
        ) !void;
    };
};