@atom-forge/rpc 0.3.2

package/dist/server/create-handler.js

@@ -0,0 +1,210 @@
+import { Packr } from "msgpackr";
+import { z } from "zod";
+import { RPC_ERROR_KEY } from "../util/constants.js";
+import { pipeline } from "../util/pipeline.js";
+import { getMiddlewares } from "./middleware.js";
+import { ServerContext } from "./server-context.js";
+import { camelToKebabCase } from "../util/string.js";
+const packr = new Packr({ structuredClone: true, useRecords: true });
+const acceptedRequests = ["GET.query", "GET.get", "POST.command"];
+const acceptedMethods = ["GET", "POST"];
+export function flattenApiDefinition(apiDefinition) {
+    const map = new Map();
+    function traverse(obj, prefix, inheritedMiddlewares) {
+        const middlewares = [...inheritedMiddlewares, ...getMiddlewares(obj)];
+        for (const key of Object.keys(obj)) {
+            const value = obj[key];
+            if (!value || typeof value !== "object")
+                continue;
+            const fullKey = prefix ? `${prefix}.${camelToKebabCase(key)}` : camelToKebabCase(key);
+            if ("rpcType" in value) {
+                const { rpcType, implementation, zodSchema } = value;
+                const methodMiddlewares = [...middlewares, ...getMiddlewares(value)];
+                const handler = (ctx) => pipeline(ctx, ...methodMiddlewares, (ctx) => {
+                    let args = ctx.getArgs();
+                    if (zodSchema)
+                        args = zodSchema.parse(args);
+                    return implementation(args, ctx);
+                });
+                map.set(fullKey, { rpcType, handler });
+            }
+            else {
+                traverse(value, fullKey, middlewares);
+            }
+        }
+    }
+    traverse(apiDefinition, "", []);
+    return map;
+}
+/**
+ * Creates a framework-agnostic handler function for processing RPC requests.
+ *
+ * @param endpointMap - The flattened API endpoint map produced by `flattenApiDefinition`.
+ * @param options
+ * @return An async function that accepts a standard `Request`, route info, and an optional adapter context.
+ */
+export function createCoreHandler(endpointMap, options) {
+    const createServerContext = options?.createServerContext ||
+        ((args, request, adapterContext) => new ServerContext(args, request, adapterContext));
+    return async function coreHandler(request, routeInfo, adapterContext) {
+        if (!acceptedMethods.includes(request.method))
+            return new Response("Method not allowed", { status: 405 });
+        if (!routeInfo.path)
+            return new Response("RPC method not found", { status: 404 });
+        const entry = endpointMap.get(routeInfo.path);
+        if (!entry)
+            return new Response("RPC method not found", { status: 404 });
+        const { rpcType, handler: rpcHandler } = entry;
+        if (!acceptedRequests.includes(request.method + "." + rpcType))
+            return new Response(`RPC type ${rpcType} not allowed for ${request.method} requests`, { status: 405 });
+        let args;
+        try {
+            switch (rpcType) {
+                case "get":
+                    args = parseGet(new URL(request.url));
+                    break;
+                case "query":
+                    args = parseQuery(new URL(request.url));
+                    break;
+                case "command":
+                    const requestContentType = request.headers.get("Content-Type") || "";
+                    if (requestContentType.includes("multipart/form-data")) {
+                        args = await parseCommandMultipartFormData(request);
+                    }
+                    else if (requestContentType.includes("application/json")) {
+                        args = await parseCommandJson(request);
+                    }
+                    else if (requestContentType.includes("application/msgpack") || requestContentType === "") {
+                        args = await parseCommandMsgpackr(request);
+                    }
+                    else {
+                        return new Response(`Unsupported Content-Type: ${requestContentType}`, { status: 415 });
+                    }
+                    break;
+            }
+        }
+        catch (e) {
+            if (e instanceof ParseError)
+                return new Response(e.message, { status: 400 });
+            console.error("[rpc] Unexpected error during request parsing:", e);
+            return new Response("Internal server error", { status: 500 });
+        }
+        const ctx = createServerContext(args, request, adapterContext);
+        try {
+            const result = await rpcHandler(ctx);
+            return makeResponse(result, ctx, request);
+        }
+        catch (e) {
+            if (e instanceof z.ZodError) {
+                ctx.cache.set(0);
+                return makeResponse({ [RPC_ERROR_KEY]: "INVALID_ARGUMENT", issues: e.issues }, ctx, request);
+            }
+            console.error("[rpc] Unhandled error in RPC handler:", e);
+            const correlationId = crypto.randomUUID();
+            return new Response(JSON.stringify({ [RPC_ERROR_KEY]: "INTERNAL_ERROR", correlationId }), { status: 500, headers: { "Content-Type": "application/json" } });
+        }
+    };
+}
+function makeResponse(result, ctx, request) {
+    const prefersJson = request.headers.get("Accept")?.includes("application/json");
+    ctx.headers.response.set("x-atom-forge-rpc-exec-time", `${ctx.elapsedTime}`);
+    ctx.headers.response.set("Content-Type", prefersJson ? "application/json" : "application/msgpack");
+    if (request.method === "GET" && ctx.cache.get()) {
+        ctx.headers.response.set("Cache-Control", `public, max-age=${ctx.cache.get()}`);
+    }
+    let body;
+    if (prefersJson) {
+        body = JSON.stringify(result);
+    }
+    else {
+        body = new Uint8Array(packr.pack(result));
+    }
+    return new Response(body, {
+        headers: ctx.headers.response,
+        status: ctx.status.get(),
+    });
+}
+function parseGet(url) {
+    let args = {};
+    url.searchParams.forEach((value, key) => (args[key] = value));
+    return args;
+}
+function parseQuery(url) {
+    let args = {};
+    try {
+        const argsParam = url.searchParams.get("args");
+        if (argsParam)
+            args = packr.unpack(Buffer.from(argsParam, "base64url"));
+    }
+    catch (e) {
+        throw new ParseError("Invalid msgpackr body");
+    }
+    return args;
+}
+async function parseCommandMsgpackr(request) {
+    let args = {};
+    try {
+        const buffer = new Uint8Array(await request.arrayBuffer());
+        if (buffer.length > 0)
+            args = packr.unpack(buffer) || {};
+    }
+    catch (e) {
+        throw new ParseError("Invalid msgpackr body");
+    }
+    return args;
+}
+async function parseCommandJson(request) {
+    let args = {};
+    try {
+        const text = await request.text();
+        if (text)
+            args = JSON.parse(text) || {};
+    }
+    catch (e) {
+        throw new ParseError("Invalid JSON body");
+    }
+    return args;
+}
+async function parseCommandMultipartFormData(request) {
+    let args = {};
+    const formData = await request.formData();
+    const argsBlob = formData.get("args");
+    if (argsBlob instanceof Blob) {
+        const buffer = new Uint8Array(await argsBlob.arrayBuffer());
+        switch (argsBlob.type) {
+            case "application/json":
+                try {
+                    args = JSON.parse(new TextDecoder().decode(buffer)) || {};
+                }
+                catch (e) {
+                    throw new ParseError("Invalid JSON in args blob");
+                }
+                break;
+            case "application/msgpack":
+                try {
+                    args = packr.unpack(buffer) || {};
+                }
+                catch (e) {
+                    throw new ParseError("Invalid msgpack in args blob");
+                }
+                break;
+            default:
+                throw new ParseError(`Unsupported args type: ${argsBlob.type}`);
+        }
+    }
+    const keys = new Set();
+    formData.forEach((_, key) => keys.add(key));
+    for (const key of keys) {
+        if (key === "args")
+            continue;
+        if (key.endsWith("[]")) {
+            args[key.substring(0, key.length - 2)] = formData.getAll(key);
+        }
+        else {
+            args[key] = formData.get(key);
+        }
+    }
+    return args;
+}
+class ParseError extends Error {
+}

package/dist/server/errors.d.ts

@@ -0,0 +1,10 @@
+export declare function invalidArgument(details?: Record<string, any>): {
+    "atomforge.rpc.error": "INVALID_ARGUMENT";
+};
+export declare function permissionDenied(details?: Record<string, any>): {
+    "atomforge.rpc.error": "PERMISSION_DENIED";
+};
+export declare function internalError(details?: Record<string, any>): {
+    "atomforge.rpc.error": "INTERNAL_ERROR";
+    correlationId: `${string}-${string}-${string}-${string}-${string}`;
+};

package/dist/server/errors.js

@@ -0,0 +1,14 @@
+import { RPC_ERROR_KEY } from "../util/constants.js";
+export function invalidArgument(details) {
+    return { [RPC_ERROR_KEY]: "INVALID_ARGUMENT", ...details };
+}
+export function permissionDenied(details) {
+    return { [RPC_ERROR_KEY]: "PERMISSION_DENIED", ...details };
+}
+export function internalError(details) {
+    return {
+        [RPC_ERROR_KEY]: "INTERNAL_ERROR",
+        correlationId: crypto.randomUUID(),
+        ...details,
+    };
+}

package/dist/server/middleware.d.ts

@@ -0,0 +1,22 @@
+import type { ServerContext } from "./server-context.js";
+import type { ServerMiddleware } from "./types.js";
+/**
+ * Retrieves the middleware functions associated with the given target.
+ * @internal
+ */
+export declare function getMiddlewares<T = any>(target: any): T[];
+/**
+ * Adds ServerMiddleware to the given target. When the target is an array, it adds the middlewares to all targets.
+ * @param target
+ * @param middleware
+ * @internal
+ */
+export declare function addMiddleware<TARGET>(target: TARGET, middleware: ServerMiddleware | ServerMiddleware[]): TARGET;
+/**
+ * Creates a ServerMiddleware function.
+ * @param middleware
+ * @param accessors
+ */
+export declare function makeServerMiddleware<ACCESSORS extends {
+    [key: string]: (ctx: ServerContext) => any;
+}>(middleware: ServerMiddleware, accessors?: ACCESSORS): ServerMiddleware & ACCESSORS;

package/dist/server/middleware.js

@@ -0,0 +1,39 @@
+const MIDDLEWARE = Symbol("MIDDLEWARE");
+/**
+ * Retrieves the middleware functions associated with the given target.
+ * @internal
+ */
+export function getMiddlewares(target) {
+    return target[MIDDLEWARE] || [];
+}
+/**
+ * Adds ServerMiddleware to the given target. When the target is an array, it adds the middlewares to all targets.
+ * @param target
+ * @param middleware
+ * @internal
+ */
+export function addMiddleware(target, middleware) {
+    if (Array.isArray(target)) {
+        target.forEach((item) => addMiddleware(item, middleware));
+    }
+    else {
+        if (!Array.isArray(middleware))
+            middleware = [middleware];
+        const t = target;
+        if (!Array.isArray(t[MIDDLEWARE]))
+            t[MIDDLEWARE] = [];
+        t[MIDDLEWARE].push(...middleware);
+    }
+    return target;
+}
+/**
+ * Creates a ServerMiddleware function.
+ * @param middleware
+ * @param accessors
+ */
+export function makeServerMiddleware(middleware, accessors) {
+    const handler = middleware;
+    if (accessors)
+        Object.assign(handler, accessors);
+    return handler;
+}

package/dist/server/rpc.d.ts

@@ -0,0 +1,65 @@
+import { z } from "zod";
+import { invalidArgument, internalError, permissionDenied } from "./errors.js";
+import { RPC_ERROR_KEY } from "../util/constants.js";
+import type { ServerContext } from "./server-context.js";
+import type { RpcMethodImplementationDescriptor, ServerMiddleware } from "./types.js";
+export declare function rpcFactory<SERVER_CONTEXT extends ServerContext = ServerContext>(): {
+    query: <ARGS, RET>(impl: (args: ARGS, ctx: SERVER_CONTEXT) => RET | Promise<RET>) => RpcMethodImplementationDescriptor<ARGS, RET, "query">;
+    command: <ARGS, RET>(impl: (args: ARGS, ctx: SERVER_CONTEXT) => RET | Promise<RET>) => RpcMethodImplementationDescriptor<ARGS, RET, "command">;
+    get: <ARGS, RET>(impl: (args: ARGS, ctx: SERVER_CONTEXT) => RET | Promise<RET>) => RpcMethodImplementationDescriptor<ARGS, RET, "get">;
+    middleware(mw: ServerMiddleware | ServerMiddleware[]): {
+        on<TARGET>(target: TARGET): TARGET;
+        query: <ARGS, RET>(impl: (args: ARGS, ctx: SERVER_CONTEXT) => RET | Promise<RET>) => RpcMethodImplementationDescriptor<ARGS, RET, "query">;
+        command: <ARGS, RET>(impl: (args: ARGS, ctx: SERVER_CONTEXT) => RET | Promise<RET>) => RpcMethodImplementationDescriptor<ARGS, RET, "command">;
+        get: <ARGS, RET>(impl: (args: ARGS, ctx: SERVER_CONTEXT) => RET | Promise<RET>) => RpcMethodImplementationDescriptor<ARGS, RET, "get">;
+        zod: <TArgsSchema extends Record<string, z.ZodTypeAny>>(schemaDef: TArgsSchema) => {
+            query: <TRet>(impl: (args: z.core.$InferObjectOutput<{ -readonly [P in keyof TArgsSchema]: TArgsSchema[P]; }, {}>, ctx: SERVER_CONTEXT) => TRet | Promise<TRet>) => RpcMethodImplementationDescriptor<z.core.$InferObjectOutput<{ -readonly [P in keyof TArgsSchema]: TArgsSchema[P]; }, {}>, TRet, "query">;
+            command: <TRet>(impl: (args: z.core.$InferObjectOutput<{ -readonly [P in keyof TArgsSchema]: TArgsSchema[P]; }, {}>, ctx: SERVER_CONTEXT) => TRet | Promise<TRet>) => RpcMethodImplementationDescriptor<z.core.$InferObjectOutput<{ -readonly [P in keyof TArgsSchema]: TArgsSchema[P]; }, {}>, TRet, "command">;
+            get: <TRet>(impl: (args: z.core.$InferObjectOutput<{ -readonly [P in keyof TArgsSchema]: TArgsSchema[P]; }, {}>, ctx: SERVER_CONTEXT) => TRet | Promise<TRet>) => RpcMethodImplementationDescriptor<z.core.$InferObjectOutput<{ -readonly [P in keyof TArgsSchema]: TArgsSchema[P]; }, {}>, TRet, "get">;
+        };
+    };
+    zod: <TArgsSchema extends Record<string, z.ZodTypeAny>>(schemaDef: TArgsSchema) => {
+        query: <TRet>(impl: (args: z.core.$InferObjectOutput<{ -readonly [P in keyof TArgsSchema]: TArgsSchema[P]; }, {}>, ctx: SERVER_CONTEXT) => TRet | Promise<TRet>) => RpcMethodImplementationDescriptor<z.core.$InferObjectOutput<{ -readonly [P in keyof TArgsSchema]: TArgsSchema[P]; }, {}>, TRet, "query">;
+        command: <TRet>(impl: (args: z.core.$InferObjectOutput<{ -readonly [P in keyof TArgsSchema]: TArgsSchema[P]; }, {}>, ctx: SERVER_CONTEXT) => TRet | Promise<TRet>) => RpcMethodImplementationDescriptor<z.core.$InferObjectOutput<{ -readonly [P in keyof TArgsSchema]: TArgsSchema[P]; }, {}>, TRet, "command">;
+        get: <TRet>(impl: (args: z.core.$InferObjectOutput<{ -readonly [P in keyof TArgsSchema]: TArgsSchema[P]; }, {}>, ctx: SERVER_CONTEXT) => TRet | Promise<TRet>) => RpcMethodImplementationDescriptor<z.core.$InferObjectOutput<{ -readonly [P in keyof TArgsSchema]: TArgsSchema[P]; }, {}>, TRet, "get">;
+    };
+    error: {
+        make<TCode extends string, TResult extends Record<string, any> = Record<never, never>>(code: TCode, message?: string, result?: TResult): { [K in typeof RPC_ERROR_KEY]: TCode; } & {
+            message?: string;
+        } & TResult;
+        invalidArgument: typeof invalidArgument;
+        permissionDenied: typeof permissionDenied;
+        internalError: typeof internalError;
+    };
+};
+export declare const rpc: {
+    query: <ARGS, RET>(impl: (args: ARGS, ctx: ServerContext<unknown>) => RET | Promise<RET>) => RpcMethodImplementationDescriptor<ARGS, RET, "query">;
+    command: <ARGS, RET>(impl: (args: ARGS, ctx: ServerContext<unknown>) => RET | Promise<RET>) => RpcMethodImplementationDescriptor<ARGS, RET, "command">;
+    get: <ARGS, RET>(impl: (args: ARGS, ctx: ServerContext<unknown>) => RET | Promise<RET>) => RpcMethodImplementationDescriptor<ARGS, RET, "get">;
+    middleware(mw: ServerMiddleware | ServerMiddleware[]): {
+        on<TARGET>(target: TARGET): TARGET;
+        query: <ARGS, RET>(impl: (args: ARGS, ctx: ServerContext<unknown>) => RET | Promise<RET>) => RpcMethodImplementationDescriptor<ARGS, RET, "query">;
+        command: <ARGS, RET>(impl: (args: ARGS, ctx: ServerContext<unknown>) => RET | Promise<RET>) => RpcMethodImplementationDescriptor<ARGS, RET, "command">;
+        get: <ARGS, RET>(impl: (args: ARGS, ctx: ServerContext<unknown>) => RET | Promise<RET>) => RpcMethodImplementationDescriptor<ARGS, RET, "get">;
+        zod: <TArgsSchema extends Record<string, z.ZodTypeAny>>(schemaDef: TArgsSchema) => {
+            query: <TRet>(impl: (args: z.core.$InferObjectOutput<{ -readonly [P in keyof TArgsSchema]: TArgsSchema[P]; }, {}>, ctx: ServerContext<unknown>) => TRet | Promise<TRet>) => RpcMethodImplementationDescriptor<z.core.$InferObjectOutput<{ -readonly [P in keyof TArgsSchema]: TArgsSchema[P]; }, {}>, TRet, "query">;
+            command: <TRet>(impl: (args: z.core.$InferObjectOutput<{ -readonly [P in keyof TArgsSchema]: TArgsSchema[P]; }, {}>, ctx: ServerContext<unknown>) => TRet | Promise<TRet>) => RpcMethodImplementationDescriptor<z.core.$InferObjectOutput<{ -readonly [P in keyof TArgsSchema]: TArgsSchema[P]; }, {}>, TRet, "command">;
+            get: <TRet>(impl: (args: z.core.$InferObjectOutput<{ -readonly [P in keyof TArgsSchema]: TArgsSchema[P]; }, {}>, ctx: ServerContext<unknown>) => TRet | Promise<TRet>) => RpcMethodImplementationDescriptor<z.core.$InferObjectOutput<{ -readonly [P in keyof TArgsSchema]: TArgsSchema[P]; }, {}>, TRet, "get">;
+        };
+    };
+    zod: <TArgsSchema extends Record<string, z.ZodTypeAny>>(schemaDef: TArgsSchema) => {
+        query: <TRet>(impl: (args: z.core.$InferObjectOutput<{ -readonly [P in keyof TArgsSchema]: TArgsSchema[P]; }, {}>, ctx: ServerContext<unknown>) => TRet | Promise<TRet>) => RpcMethodImplementationDescriptor<z.core.$InferObjectOutput<{ -readonly [P in keyof TArgsSchema]: TArgsSchema[P]; }, {}>, TRet, "query">;
+        command: <TRet>(impl: (args: z.core.$InferObjectOutput<{ -readonly [P in keyof TArgsSchema]: TArgsSchema[P]; }, {}>, ctx: ServerContext<unknown>) => TRet | Promise<TRet>) => RpcMethodImplementationDescriptor<z.core.$InferObjectOutput<{ -readonly [P in keyof TArgsSchema]: TArgsSchema[P]; }, {}>, TRet, "command">;
+        get: <TRet>(impl: (args: z.core.$InferObjectOutput<{ -readonly [P in keyof TArgsSchema]: TArgsSchema[P]; }, {}>, ctx: ServerContext<unknown>) => TRet | Promise<TRet>) => RpcMethodImplementationDescriptor<z.core.$InferObjectOutput<{ -readonly [P in keyof TArgsSchema]: TArgsSchema[P]; }, {}>, TRet, "get">;
+    };
+    error: {
+        make<TCode extends string, TResult extends Record<string, any> = Record<never, never>>(code: TCode, message?: string, result?: TResult | undefined): {
+            "atomforge.rpc.error": TCode;
+        } & {
+            message?: string;
+        } & TResult;
+        invalidArgument: typeof invalidArgument;
+        permissionDenied: typeof permissionDenied;
+        internalError: typeof internalError;
+    };
+};

package/dist/server/rpc.js

@@ -0,0 +1,49 @@
+import { z } from "zod";
+import { invalidArgument, internalError, permissionDenied } from "./errors.js";
+import { RPC_ERROR_KEY } from "../util/constants.js";
+import { addMiddleware } from "./middleware.js";
+export function rpcFactory() {
+    function makeDescriptor(rpcType, implementation, zodSchema, middleware) {
+        const descriptor = {
+            rpcType,
+            implementation: implementation,
+            ...(zodSchema && { zodSchema }),
+        };
+        return middleware ? addMiddleware(descriptor, middleware) : descriptor;
+    }
+    function makeZodMethodSet(schemaDef, middleware) {
+        const schema = z.object(schemaDef);
+        return {
+            query: (impl) => makeDescriptor("query", impl, schema, middleware),
+            command: (impl) => makeDescriptor("command", impl, schema, middleware),
+            get: (impl) => makeDescriptor("get", impl, schema, middleware),
+        };
+    }
+    return {
+        query: (impl) => makeDescriptor("query", impl),
+        command: (impl) => makeDescriptor("command", impl),
+        get: (impl) => makeDescriptor("get", impl),
+        middleware(mw) {
+            return {
+                on(target) {
+                    addMiddleware(target, mw);
+                    return target;
+                },
+                query: (impl) => makeDescriptor("query", impl, undefined, mw),
+                command: (impl) => makeDescriptor("command", impl, undefined, mw),
+                get: (impl) => makeDescriptor("get", impl, undefined, mw),
+                zod: (schemaDef) => makeZodMethodSet(schemaDef, mw),
+            };
+        },
+        zod: (schemaDef) => makeZodMethodSet(schemaDef),
+        error: {
+            make(code, message, result) {
+                return { [RPC_ERROR_KEY]: code, ...(message !== undefined && { message }), ...(result ?? {}) };
+            },
+            invalidArgument,
+            permissionDenied,
+            internalError,
+        },
+    };
+}
+export const rpc = rpcFactory();

package/dist/server/server-context.d.ts

@@ -0,0 +1,79 @@
+import { CookieManager } from "../util/cookies.js";
+/**
+ * The ServerContext class represents the context of a server request, holding
+ * details such as headers, arguments, environment variables, caching, and status management.
+ * It is designed to provide a streamlined interface for interacting with server-side request data.
+ * @internal
+ */
+export declare class ServerContext<TAdapter = unknown> {
+    readonly request: Request;
+    readonly adapterContext: TAdapter;
+    private _cache;
+    private _status;
+    private readonly start;
+    /** A Map object representing arguments passed to the server */
+    readonly args: Map<string, any>;
+    /** An object containing request and response headers */
+    readonly headers: {
+        request: Headers;
+        response: Headers;
+    };
+    /** Framework-agnostic cookie manager */
+    readonly cookies: CookieManager;
+    /** Indicates the time elapsed since the creation of the ServerContext instance */
+    get elapsedTime(): number;
+    constructor(args: Record<string, any> | undefined, request: Request, adapterContext: TAdapter);
+    /** Retrieves all arguments as a plain JavaScript object */
+    getArgs(): Record<string, any>;
+    /** A Map of custom environment variables relevant to the server context. */
+    readonly env: Map<string | symbol, any>;
+    /** An object with methods to set and get cache duration. */
+    readonly cache: {
+        set: (seconds: number) => number;
+        get: () => number;
+    };
+    /** An object providing methods to set or retrieve response status codes, as well as predefined shortcuts for common HTTP status codes. */
+    readonly status: {
+        set: (status: number) => number;
+        get: () => number;
+        continue: () => number;
+        switchingProtocols: () => number;
+        processing: () => number;
+        ok: () => number;
+        created: () => number;
+        accepted: () => number;
+        noContent: () => number;
+        resetContent: () => number;
+        partialContent: () => number;
+        multipleChoices: () => number;
+        movedPermanently: () => number;
+        found: () => number;
+        seeOther: () => number;
+        notModified: () => number;
+        temporaryRedirect: () => number;
+        permanentRedirect: () => number;
+        badRequest: () => number;
+        unauthorized: () => number;
+        paymentRequired: () => number;
+        forbidden: () => number;
+        notFound: () => number;
+        methodNotAllowed: () => number;
+        notAcceptable: () => number;
+        conflict: () => number;
+        gone: () => number;
+        lengthRequired: () => number;
+        preconditionFailed: () => number;
+        payloadTooLarge: () => number;
+        uriTooLong: () => number;
+        badContent: () => number;
+        rangeNotSatisfiable: () => number;
+        expectationFailed: () => number;
+        tooManyRequests: () => number;
+        serverError: () => number;
+        notImplemented: () => number;
+        badGateway: () => number;
+        serviceUnavailable: () => number;
+        gatewayTimeout: () => number;
+        httpVersionNotSupported: () => number;
+    };
+}

package/dist/server/server-context.js

@@ -0,0 +1,86 @@
+import { CookieManager } from "../util/cookies.js";
+/**
+ * The ServerContext class represents the context of a server request, holding
+ * details such as headers, arguments, environment variables, caching, and status management.
+ * It is designed to provide a streamlined interface for interacting with server-side request data.
+ * @internal
+ */
+export class ServerContext {
+    /** Indicates the time elapsed since the creation of the ServerContext instance */
+    get elapsedTime() {
+        return performance.now() - this.start;
+    }
+    constructor(args, request, adapterContext) {
+        this.request = request;
+        this.adapterContext = adapterContext;
+        this._cache = 0;
+        this._status = 200;
+        /** A Map of custom environment variables relevant to the server context. */
+        this.env = new Map();
+        /** An object with methods to set and get cache duration. */
+        this.cache = {
+            set: (seconds) => (this._cache = Math.max(0, Math.floor(seconds))),
+            get: () => this._cache,
+        };
+        /** An object providing methods to set or retrieve response status codes, as well as predefined shortcuts for common HTTP status codes. */
+        this.status = {
+            set: (status) => (this._status = status),
+            get: () => this._status,
+            // 1xx - Informational
+            continue: () => (this._status = 100),
+            switchingProtocols: () => (this._status = 101),
+            processing: () => (this._status = 102),
+            // 2xx - Success
+            ok: () => (this._status = 200),
+            created: () => (this._status = 201),
+            accepted: () => (this._status = 202),
+            noContent: () => (this._status = 204),
+            resetContent: () => (this._status = 205),
+            partialContent: () => (this._status = 206),
+            // 3xx - Redirection
+            multipleChoices: () => (this._status = 300),
+            movedPermanently: () => (this._status = 301),
+            found: () => (this._status = 302),
+            seeOther: () => (this._status = 303),
+            notModified: () => (this._status = 304),
+            temporaryRedirect: () => (this._status = 307),
+            permanentRedirect: () => (this._status = 308),
+            // 4xx - Client Error
+            badRequest: () => (this._status = 400),
+            unauthorized: () => (this._status = 401),
+            paymentRequired: () => (this._status = 402),
+            forbidden: () => (this._status = 403),
+            notFound: () => (this._status = 404),
+            methodNotAllowed: () => (this._status = 405),
+            notAcceptable: () => (this._status = 406),
+            conflict: () => (this._status = 409),
+            gone: () => (this._status = 410),
+            lengthRequired: () => (this._status = 411),
+            preconditionFailed: () => (this._status = 412),
+            payloadTooLarge: () => (this._status = 413),
+            uriTooLong: () => (this._status = 414),
+            badContent: () => (this._status = 415),
+            rangeNotSatisfiable: () => (this._status = 416),
+            expectationFailed: () => (this._status = 417),
+            tooManyRequests: () => (this._status = 429),
+            // 5xx - Server Error
+            serverError: () => (this._status = 500),
+            notImplemented: () => (this._status = 501),
+            badGateway: () => (this._status = 502),
+            serviceUnavailable: () => (this._status = 503),
+            gatewayTimeout: () => (this._status = 504),
+            httpVersionNotSupported: () => (this._status = 505),
+        };
+        this.start = performance.now();
+        this.args = new Map(Object.entries(args || {}));
+        this.headers = {
+            request: request.headers,
+            response: new Headers(),
+        };
+        this.cookies = new CookieManager(request.headers, this.headers.response);
+    }
+    /** Retrieves all arguments as a plain JavaScript object */
+    getArgs() {
+        return Object.fromEntries(this.args);
+    }
+}

package/dist/server/types.d.ts

@@ -0,0 +1,30 @@
+import { z } from "zod";
+import type { RpcMethodDescriptor } from "../client/types.js";
+import type { Middleware } from "../util/pipeline.js";
+import type { ServerContext } from "./server-context.js";
+/**
+ * Represents middleware for handling server-specific logic within the application lifecycle.
+ * @internal
+ */
+export type ServerMiddleware<RET = any> = Middleware<ServerContext, RET>;
+/**
+ * Server-side descriptor that contains the actual implementation.
+ * @internal
+ */
+export interface RpcMethodImplementationDescriptor<ARGS, RET, Type extends "query" | "command" | "get"> extends RpcMethodDescriptor {
+    rpcType: Type;
+    zodSchema?: z.ZodSchema<ARGS>;
+    implementation: (args: ARGS) => RET | Promise<RET>;
+}
+/**
+ * Helper type for extracting the Zod schema
+ * @internal
+ */
+export type GetZodSchema<T> = T extends RpcMethodImplementationDescriptor<any, any, any> ? T["zodSchema"] : undefined;
+/**
+ * This generic type is for the API definition on the server side.
+ * @internal
+ */
+export type ApiDefinition<T> = {
+    [K in keyof T]: T[K] extends RpcMethodImplementationDescriptor<any, any, any> ? T[K] : T[K] extends object ? ApiDefinition<T[K]> : T[K];
+};

package/dist/server/types.js

@@ -0,0 +1 @@
+export {};

package/dist/util/constants.d.ts

@@ -0,0 +1 @@
+export declare const RPC_ERROR_KEY: "atomforge.rpc.error";

package/dist/util/constants.js

@@ -0,0 +1 @@
+export const RPC_ERROR_KEY = "atomforge.rpc.error";

package/dist/util/cookies.d.ts

@@ -0,0 +1,22 @@
+export interface CookieOptions {
+    maxAge?: number;
+    expires?: Date;
+    path?: string;
+    domain?: string;
+    secure?: boolean;
+    httpOnly?: boolean;
+    sameSite?: "Strict" | "Lax" | "None";
+}
+export declare class CookieManager {
+    private readonly requestHeaders;
+    private readonly responseHeaders;
+    private readonly parsed;
+    constructor(requestHeaders: Headers, responseHeaders: Headers);
+    get(name: string): string | undefined;
+    getAll(): {
+        name: string;
+        value: string;
+    }[];
+    set(name: string, value: string, options?: CookieOptions): void;
+    delete(name: string, options?: Omit<CookieOptions, "maxAge">): void;
+}