valkyr/boilerplate
Template
1
0
Fork 0
Code Issues Wiki Activity

feat: checkpoint

Browse Source
This commit is contained in:
kodemon
2025-11-23 22:57:43 +01:00
parent 7df57522d2
commit 5d45e273ee
160 changed files with 10160 additions and 1476 deletions
Download Patch File Download Diff File Expand all files Collapse all files

302
platform/relay/adapters/http.ts Normal file
View File

@@ -0,0 +1,302 @@
import {
assertServerErrorResponse,
type RelayAdapter,
type RelayInput,
type RelayResponse,
type ServerErrorResponse,
} from "../libraries/adapter.ts";
import { ServerError, type ServerErrorType } from "../libraries/errors.ts";
/**
* HttpAdapter provides a unified transport layer for Relay.
*
* It supports sending JSON objects, nested structures, arrays, and file uploads
* via FormData. The adapter automatically detects the payload type and formats
* the request accordingly. Responses are normalized into `RelayResponse`.
*
* @example
* ```ts
* const adapter = new HttpAdapter({ url: "https://api.example.com" });
*
* // Sending JSON data
* const jsonResponse = await adapter.send({
* method: "POST",
* endpoint: "/users",
* body: { name: "Alice", age: 30 },
* });
*
* // Sending files and nested objects
* const formResponse = await adapter.send({
* method: "POST",
* endpoint: "/upload",
* body: {
* user: { name: "Bob", avatar: fileInput.files[0] },
* documents: [fileInput.files[1], fileInput.files[2]],
* },
* });
* ```
*/
export class HttpAdapter implements RelayAdapter {
/**
* Instantiate a new HttpAdapter instance.
*
* @param options - Adapter options.
*/
constructor(readonly options: HttpAdapterOptions) {}
/**
* Override the initial url value set by instantiator.
*/
set url(value: string) {
this.options.url = value;
}
/**
* Retrieve the URL value from options object.
*/
get url() {
return this.options.url;
}
/**
* Return the full URL from given endpoint.
*
* @param endpoint - Endpoint to get url for.
*/
getUrl(endpoint: string): string {
return `${this.url}${endpoint}`;
}
async send({ method, endpoint, query, body, headers = new Headers() }: RelayInput): Promise<RelayResponse> {
const init: RequestInit = { method, headers };
// ### Before Request
// If any before request hooks has been defined, we run them here passing in the
// request headers for further modification.
await this.#beforeRequest(headers);
// ### Body
if (body !== undefined) {
const type = this.#getRequestFormat(body);
if (type === "form-data") {
headers.delete("content-type");
init.body = this.#getFormData(body);
}
if (type === "json") {
headers.set("content-type", "application/json");
init.body = JSON.stringify(body);
}
}
// ### Response
return this.request(`${endpoint}${query}`, init);
}
/**
* Send a fetch request using the given fetch options and returns
* a relay formatted response.
*
* @param endpoint - Which endpoint to submit request to.
* @param init - Request init details to submit with the request.
*/
async request(endpoint: string, init?: RequestInit): Promise<RelayResponse> {
return this.#toResponse(await fetch(this.getUrl(endpoint), init));
}
/**
* Run before request operations.
*
* @param headers - Headers to pass to hooks.
*/
async #beforeRequest(headers: Headers) {
if (this.options.hooks?.beforeRequest !== undefined) {
for (const hook of this.options.hooks.beforeRequest) {
await hook(headers);
}
}
}
/**
* Determine the parser method required for the request.
*
* @param body - Request body.
*/
#getRequestFormat(body: unknown): "form-data" | "json" {
if (body instanceof FormData) {
return "form-data";
}
if (containsFile(body) === true) {
return "form-data";
}
return "json";
}
/**
* Get FormData instance for the given body.
*
* @param body - Request body.
*/
#getFormData(data: Record<string, unknown>, formData = new FormData(), parentKey?: string): FormData {
for (const key in data) {
const value = data[key];
if (value === undefined || value === null) continue;
const formKey = parentKey ? `${parentKey}[${key}]` : key;
if (value instanceof File) {
formData.append(formKey, value, value.name);
} else if (Array.isArray(value)) {
value.forEach((item, index) => {
if (item instanceof File) {
formData.append(`${formKey}[${index}]`, item, item.name);
} else if (typeof item === "object") {
this.#getFormData(item as Record<string, unknown>, formData, `${formKey}[${index}]`);
} else {
formData.append(`${formKey}[${index}]`, String(item));
}
});
} else if (typeof value === "object") {
this.#getFormData(value as Record<string, unknown>, formData, formKey);
} else {
formData.append(formKey, String(value));
}
}
return formData;
}
/**
* Convert a fetch response to a compliant relay response.
*
* @param response - Fetch response to convert.
*/
async #toResponse(response: Response): Promise<RelayResponse> {
const type = response.headers.get("content-type");
// ### Content Type
// Ensure that the server responds with a 'content-type' definition. We should
// always expect the server to respond with a type.
if (type === null) {
return {
result: "error",
headers: response.headers,
error: {
code: "CONTENT_TYPE_MISSING",
status: response.status,
message: "Missing 'content-type' in header returned from server.",
},
};
}
// ### Empty Response
// If the response comes back with empty response status 204 we simply return a
// empty success.
if (response.status === 204) {
return {
result: "success",
headers: response.headers,
data: null,
};
}
// ### JSON
// If the 'content-type' contains 'json' we treat it as a 'json' compliant response
// and attempt to resolve it as such.
if (type.includes("json") === true) {
const parsed = await response.json();
if ("data" in parsed) {
return {
result: "success",
headers: response.headers,
data: parsed.data,
};
}
if ("error" in parsed) {
return {
result: "error",
headers: response.headers,
error: this.#toError(parsed),
};
}
return {
result: "error",
headers: response.headers,
error: {
code: "INVALID_SERVER_RESPONSE",
status: response.status,
message: "Unsupported 'json' body returned from server, missing 'data' or 'error' key.",
},
};
}
// ### Error
// If the 'content-type' is not a JSON response from the API then we check if the
// response status is an error code.
if (response.status >= 400) {
return {
result: "error",
headers: response.headers,
error: {
code: "SERVER_ERROR_RESPONSE",
status: response.status,
message: await response.text(),
},
};
}
// ### Success
// If the 'content-type' is not a JSON response from the API and the request is not
// an error we simply return the pure response in the data key.
return {
result: "success",
headers: response.headers,
data: response,
};
}
#toError(candidate: unknown, status: number = 500): ServerErrorType | ServerErrorResponse["error"] {
if (assertServerErrorResponse(candidate)) {
return ServerError.fromJSON(candidate.error);
}
if (typeof candidate === "string") {
return {
code: "ERROR",
status,
message: candidate,
};
}
return {
code: "UNSUPPORTED_SERVER_ERROR",
status,
message: "Unsupported 'error' returned from server.",
};
}
}
function containsFile(value: unknown): boolean {
if (value instanceof File) {
return true;
}
if (Array.isArray(value)) {
return value.some(containsFile);
}
if (typeof value === "object" && value !== null) {
return Object.values(value).some(containsFile);
}
return false;
}
export type HttpAdapterOptions = {
url: string;
hooks?: {
beforeRequest?: ((headers: Headers) => Promise<void>)[];
};
};

89
platform/relay/libraries/adapter.ts Normal file
View File

@@ -0,0 +1,89 @@
import z from "zod";
import type { ServerErrorType } from "./errors.ts";
import type { RouteMethod } from "./route.ts";
/*
|--------------------------------------------------------------------------------
| Types
|--------------------------------------------------------------------------------
*/
const ServerErrorResponseSchema = z.object({
error: z.object({
code: z.any(),
status: z.number(),
message: z.string(),
data: z.any().optional(),
}),
});
/*
|--------------------------------------------------------------------------------
| Utilities
|--------------------------------------------------------------------------------
*/
/**
* Check if the given candidate is a valid relay error response.
*
* @param candidate - Candidate to check.
*/
export function assertServerErrorResponse(candidate: unknown): candidate is ServerErrorResponse {
return ServerErrorResponseSchema.safeParse(candidate).success;
}
/*
|--------------------------------------------------------------------------------
| Types
|--------------------------------------------------------------------------------
*/
export type RelayAdapter = {
readonly url: string;
/**
* Return the full URL from given endpoint.
*
* @param endpoint - Endpoint to get url for.
*/
getUrl(endpoint: string): string;
/**
* Send a request to the configured relay url.
*
* @param input - Request input parameters.
* @param publicKey - Key to encrypt the payload with.
*/
send(input: RelayInput, publicKey?: string): Promise<RelayResponse>;
/**
* Sends a fetch request using the given options and returns a
* raw response.
*
* @param options - Relay request options.
*/
request(input: RequestInfo | URL, init?: RequestInit): Promise<RelayResponse>;
};
export type RelayInput = {
method: RouteMethod;
endpoint: string;
query?: string;
body?: Record<string, unknown>;
headers?: Headers;
};
export type RelayResponse<TData = unknown, TError = ServerErrorType | ServerErrorResponse["error"]> =
| {
result: "success";
headers: Headers;
data: TData;
}
| {
result: "error";
headers: Headers;
error: TError;
};
export type ServerErrorResponse = z.infer<typeof ServerErrorResponseSchema>;

198
platform/relay/libraries/client.ts Normal file
View File

@@ -0,0 +1,198 @@
/* eslint-disable @typescript-eslint/no-empty-object-type */
import type { ZodObject, ZodType } from "zod";
import type { RelayAdapter, RelayInput, RelayResponse } from "./adapter.ts";
import { Route, type RouteFn, type Routes } from "./route.ts";
/**
* Factory method for generating a new relay client instance.
*
* @param config - Client configuration.
* @param procedures - Map of routes to make available to the client.
*/
export function makeClient<TRoutes extends Routes>(config: Config, routes: TRoutes): RelayClient<TRoutes> {
const client: any = {
getUrl: config.adapter.getUrl.bind(config.adapter),
request: config.adapter.request.bind(config.adapter),
};
for (const key in routes) {
const route = routes[key];
if (route instanceof Route) {
client[key] = getRouteFn(route, config);
} else if (typeof route === "function") {
client[key] = route;
} else {
client[key] = getNestedRoute(config, route);
}
}
return client;
}
/*
|--------------------------------------------------------------------------------
| Helpers
|--------------------------------------------------------------------------------
*/
function getNestedRoute<TRoutes extends Routes>(config: Config, routes: TRoutes): RelayClient<TRoutes> {
const nested: any = {};
for (const key in routes) {
const route = routes[key];
if (route instanceof Route) {
nested[key] = getRouteFn(route, config);
} else if (typeof route === "function") {
nested[key] = route;
} else {
nested[key] = getNestedRoute(config, route);
}
}
return nested;
}
function getRouteFn(route: Route, { adapter }: Config) {
return async (options: any = {}) => {
const input: RelayInput = {
method: route.state.method,
endpoint: route.state.path,
query: "",
};
// ### Params
// Prepare request parameters by replacing :param notations with the
// parameter argument provided.
if (route.state.params !== undefined) {
const params = await toParsedArgs(
route.state.params,
options.params,
`Invalid 'params' passed to ${route.state.path} handler.`,
);
for (const key in params) {
input.endpoint = input.endpoint.replace(`:${key}`, encodeURIComponent(params[key]));
}
}
// ### Query
// Prepare request query by looping through the query argument and
// creating a query string to pass onto the fetch request.
if (route.state.query !== undefined) {
const query = await toParsedArgs(
route.state.query,
options.query,
`Invalid 'query' passed to ${route.state.path} handler.`,
);
const pieces: string[] = [];
for (const key in query) {
pieces.push(`${encodeURIComponent(key)}=${encodeURIComponent(query[key])}`);
}
if (pieces.length > 0) {
input.query = `?${pieces.join("&")}`;
}
}
// ### Body
// Attach the body to the input which is handled internally based on the
// type of fetch body is submitted.
if (route.state.body !== undefined) {
input.body = await toParsedArgs(
route.state.body,
options.body,
`Invalid 'body' passed to ${route.state.path} handler.`,
);
}
// ### Request Init
// List of request init options that we can extract and forward to the
// request adapter.
if (options.headers !== undefined) {
input.headers = new Headers(options.headers);
}
// ### Fetch
const response = await adapter.send(input);
if ("data" in response && route.state.response !== undefined) {
response.data = route.state.response.parse(response.data);
}
return response;
};
}
async function toParsedArgs(
zod: ZodType,
args: unknown,
msg: string,
): Promise<Record<string, string | number | boolean>> {
const result = await zod.safeParseAsync(args);
if (result.success === false) {
throw new Error(msg);
}
return result.data as Record<string, string | number | boolean>;
}
/*
|--------------------------------------------------------------------------------
| Types
|--------------------------------------------------------------------------------
*/
export type RelayClient<TRoutes extends Routes> = RelayRequest & RelayRoutes<TRoutes>;
type RelayRequest = {
url: string;
getUrl: (endpoint: string) => string;
request: <TData = unknown>(input: RequestInfo | URL, init?: RequestInit) => Promise<RelayResponse<TData>>;
};
type RelayRoutes<TRoutes extends Routes> = {
[TKey in keyof TRoutes]: TRoutes[TKey] extends Route
? ClientRoute<TRoutes[TKey]>
: TRoutes[TKey] extends RouteFn
? TRoutes[TKey]
: TRoutes[TKey] extends Routes
? RelayRoutes<TRoutes[TKey]>
: never;
};
type ClientRoute<TRoute extends Route> = HasPayload<TRoute> extends true
? (
payload: Prettify<
(TRoute["state"]["params"] extends ZodObject ? { params: TRoute["$params"] } : {}) &
(TRoute["state"]["query"] extends ZodObject ? { query: TRoute["$query"] } : {}) &
(TRoute["state"]["body"] extends ZodType ? { body: TRoute["$body"] } : {}) & {
headers?: HeadersInit;
}
>,
) => RouteResponse<TRoute>
: (payload?: { headers: HeadersInit }) => RouteResponse<TRoute>;
type HasPayload<TRoute extends Route> = TRoute["state"]["params"] extends ZodObject
? true
: TRoute["state"]["query"] extends ZodObject
? true
: TRoute["state"]["body"] extends ZodType
? true
: false;
type RouteResponse<TRoute extends Route> = Promise<RelayResponse<RouteOutput<TRoute>, RouteErrors<TRoute>>> & {
$params: TRoute["$params"];
$query: TRoute["$query"];
$body: TRoute["$body"];
$response: TRoute["$response"];
};
type RouteOutput<TRoute extends Route> = TRoute["state"]["response"] extends ZodType ? TRoute["$response"] : null;
type RouteErrors<TRoute extends Route> = InstanceType<TRoute["state"]["errors"][number]>;
type Config = {
adapter: RelayAdapter;
};
type Prettify<T> = { [K in keyof T]: T[K] } & {};

5
platform/relay/libraries/context.ts Normal file
View File

@@ -0,0 +1,5 @@
export interface ServerContext {
id: string;
}
export const context: ServerContext = {} as any;

437
platform/relay/libraries/errors.ts Normal file
View File

@@ -0,0 +1,437 @@
import type { ZodError } from "zod";
export abstract class ServerError<TData = unknown> extends Error {
abstract readonly code: string;
constructor(
message: string,
readonly status: number,
readonly data?: TData,
) {
super(message);
}
/**
* Converts a server delivered JSON error to its native instance.
*
* @param error - Error JSON.
*/
static fromJSON(error: ServerErrorJSON): ServerErrorType {
switch (error.code) {
case "BAD_REQUEST":
return new BadRequestError(error.message, error.data);
case "UNAUTHORIZED":
return new UnauthorizedError(error.message, error.data);
case "FORBIDDEN":
return new ForbiddenError(error.message, error.data);
case "NOT_FOUND":
return new NotFoundError(error.message, error.data);
case "METHOD_NOT_ALLOWED":
return new MethodNotAllowedError(error.message, error.data);
case "NOT_ACCEPTABLE":
return new NotAcceptableError(error.message, error.data);
case "CONFLICT":
return new ConflictError(error.message, error.data);
case "GONE":
return new GoneError(error.message, error.data);
case "UNSUPPORTED_MEDIA_TYPE":
return new UnsupportedMediaTypeError(error.message, error.data);
case "UNPROCESSABLE_CONTENT":
return new UnprocessableContentError(error.message, error.data);
case "VALIDATION":
return new ValidationError(error.message, error.data);
case "INTERNAL_SERVER":
return new InternalServerError(error.message, error.data);
case "NOT_IMPLEMENTED":
return new NotImplementedError(error.message, error.data);
case "SERVICE_UNAVAILABLE":
return new ServiceUnavailableError(error.message, error.data);
default:
return new InternalServerError(error.message, error.data);
}
}
/**
* Convert error instance to a JSON object.
*/
toJSON(): ServerErrorJSON {
return {
code: this.code as ServerErrorJSON["code"],
status: this.status,
message: this.message,
data: this.data,
};
}
}
export class BadRequestError<TData = unknown> extends ServerError<TData> {
readonly code = "BAD_REQUEST";
/**
* Instantiate a new BadRequestError.
*
* The **HTTP 400 Bad Request** response status code indicates that the server
* cannot or will not process the request due to something that is perceived to
* be a client error.
*
* @param message - the message that describes the error. Default: "Bad Request".
* @param data - Optional data to send with the error.
*/
constructor(message = "Bad Request", data?: TData) {
super(message, 400, data);
}
}
export class UnauthorizedError<TData = unknown> extends ServerError<TData> {
readonly code = "UNAUTHORIZED";
/**
* Instantiate a new UnauthorizedError.
*
* The **HTTP 401 Unauthorized** response status code indicates that the client
* request has not been completed because it lacks valid authentication
* credentials for the requested resource.
*
* This status code is sent with an HTTP WWW-Authenticate response header that
* contains information on how the client can request for the resource again after
* prompting the user for authentication credentials.
*
* This status code is similar to the **403 Forbidden** status code, except that
* in situations resulting in this status code, user authentication can allow
* access to the resource.
*
* @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401
*
* @param message - Optional message to send with the error. Default: "Unauthorized".
* @param data - Optional data to send with the error.
*/
constructor(message = "Unauthorized", data?: TData) {
super(message, 401, data);
}
}
export class ForbiddenError<TData = unknown> extends ServerError<TData> {
readonly code = "FORBIDDEN";
/**
* Instantiate a new ForbiddenError.
*
* The **HTTP 403 Forbidden** response status code indicates that the server
* understands the request but refuses to authorize it.
*
* This status is similar to **401**, but for the **403 Forbidden** status code
* re-authenticating makes no difference. The access is permanently forbidden and
* tied to the application logic, such as insufficient rights to a resource.
*
* @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403
*
* @param message - Optional message to send with the error. Default: "Forbidden".
* @param data - Optional data to send with the error.
*/
constructor(message = "Forbidden", data?: TData) {
super(message, 403, data);
}
}
export class NotFoundError<TData = unknown> extends ServerError<TData> {
readonly code = "NOT_FOUND";
/**
* Instantiate a new NotFoundError.
*
* The **HTTP 404 Not Found** response status code indicates that the server
* cannot find the requested resource. Links that lead to a 404 page are often
* called broken or dead links and can be subject to link rot.
*
* A 404 status code only indicates that the resource is missing: not whether the
* absence is temporary or permanent. If a resource is permanently removed,
* use the **410 _(Gone)_** status instead.
*
* @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404
*
* @param message - Optional message to send with the error. Default: "Not Found".
* @param data - Optional data to send with the error.
*/
constructor(message = "Not Found", data?: TData) {
super(message, 404, data);
}
}
export class MethodNotAllowedError<TData = unknown> extends ServerError<TData> {
readonly code = "METHOD_NOT_ALLOWED";
/**
* Instantiate a new MethodNotAllowedError.
*
* The **HTTP 405 Method Not Allowed** response code indicates that the
* request method is known by the server but is not supported by the target resource.
*
* @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/405
*
* @param message - Optional message to send with the error. Default: "Method Not Allowed".
* @param data - Optional data to send with the error.
*/
constructor(message = "Method Not Allowed", data?: TData) {
super(message, 405, data);
}
}
export class NotAcceptableError<TData = unknown> extends ServerError<TData> {
readonly code = "NOT_ACCEPTABLE";
/**
* Instantiate a new NotAcceptableError.
*
* The **HTTP 406 Not Acceptable** client error response code indicates that the
* server cannot produce a response matching the list of acceptable values
* defined in the request, and that the server is unwilling to supply a default
* representation.
*
* @param message - Optional message to send with the error. Default: "Not Acceptable".
* @param data - Optional data to send with the error.
*/
constructor(message = "Not Acceptable", data?: TData) {
super(message, 406, data);
}
}
export class ConflictError<TData = unknown> extends ServerError<TData> {
readonly code = "CONFLICT";
/**
* Instantiate a new ConflictError.
*
* The **HTTP 409 Conflict** response status code indicates a request conflict
* with the current state of the target resource.
*
* Conflicts are most likely to occur in response to a PUT request. For example,
* you may get a 409 response when uploading a file that is older than the
* existing one on the server, resulting in a version control conflict.
*
* @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409
*
* @param message - Optional message to send with the error. Default: "Conflict".
* @param data - Optional data to send with the error.
*/
constructor(message = "Conflict", data?: TData) {
super(message, 409, data);
}
}
export class GoneError<TData = unknown> extends ServerError<TData> {
readonly code = "GONE";
/**
* Instantiate a new GoneError.
*
* The **HTTP 410 Gone** indicates that the target resource is no longer
* available at the origin server and that this condition is likely to be
* permanent. A 410 response is cacheable by default.
*
* Clients should not repeat requests for resources that return a 410 response,
* and website owners should remove or replace links that return this code. If
* server owners don't know whether this condition is temporary or permanent,
* a 404 status code should be used instead.
*
* @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/410
*
* @param message - Optional message to send with the error. Default: "Gone".
* @param data - Optional data to send with the error.
*/
constructor(message = "Gone", data?: TData) {
super(message, 410, data);
}
}
export class UnsupportedMediaTypeError<TData = unknown> extends ServerError<TData> {
readonly code = "UNSUPPORTED_MEDIA_TYPE";
/**
* Instantiate a new UnsupportedMediaTypeError.
*
* The **HTTP 415 Unsupported Media Type** response code indicates that the
* server refuses to accept the request because the payload format is in an unsupported format.
*
* @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/415
*
* @param message - Optional message to send with the error. Default: "Unsupported Media Type".
* @param data - Optional data to send with the error.
*/
constructor(message = "Unsupported Media Type", data?: TData) {
super(message, 415, data);
}
}
export class UnprocessableContentError<TData = unknown> extends ServerError<TData> {
readonly code = "UNPROCESSABLE_CONTENT";
/**
* Instantiate a new UnprocessableContentError.
*
* The **HTTP 422 Unprocessable Content** client error response status code
* indicates that the server understood the content type of the request entity,
* and the syntax of the request entity was correct, but it was unable to
* process the contained instructions.
*
* Clients that receive a 422 response should expect that repeating the request
* without modification will fail with the same error.
*
* @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422
*
* @param message - Optional message to send with the error. Default: "Unprocessable Content".
* @param data - Optional data to send with the error.
*/
constructor(message = "Unprocessable Content", data?: TData) {
super(message, 422, data);
}
}
export class ValidationError<TData = unknown> extends ServerError<TData> {
readonly code = "VALIDATION";
/**
* Instantiate a new ValidationError.
*
* This indicates that the server understood the request, but the content
* failed semantic validation against the expected schema.
*
* @param message - Optional message to send with the error. Default: "Validation Failed".
* @param data - Data with validation failure details.
*/
constructor(message = "Validation Failed", data: TData) {
super(message, 422, data);
}
/**
* Instantiate a new ValidationError.
*
* This indicates that the server understood the request, but the content
* failed semantic validation against the expected schema.
*
* @param zodError - The original ZodError instance.
* @param source - The source of the validation error.
* @param message - Optional override for the main error message.
*/
static fromZod(zodError: ZodError, source: ErrorSource, message?: string) {
return new ValidationError(message, {
details: zodError.issues.map((issue) => {
return {
source: source,
code: issue.code,
field: issue.path.join("."),
message: issue.message,
};
}),
} satisfies ValidationErrorData);
}
}
export class InternalServerError<TData = unknown> extends ServerError<TData> {
readonly code = "INTERNAL_SERVER";
/**
* Instantiate a new InternalServerError.
*
* The **HTTP 500 Internal Server Error** server error response code indicates that
* the server encountered an unexpected condition that prevented it from fulfilling
* the request.
*
* This error response is a generic "catch-all" response. Usually, this indicates
* the server cannot find a better 5xx error code to response. Sometimes, server
* administrators log error responses like the 500 status code with more details
* about the request to prevent the error from happening again in the future.
*
* @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500
*
* @param message - Optional message to send with the error. Default: "Internal Server Error".
* @param data - Optional data to send with the error.
*/
constructor(message = "Internal Server Error", data?: TData) {
super(message, 500, data);
}
}
export class NotImplementedError<TData = unknown> extends ServerError<TData> {
readonly code = "NOT_IMPLEMENTED";
/**
* Instantiate a new NotImplementedError.
*
* The **HTTP 501 Not Implemented** server error response status code means that
* the server does not support the functionality required to fulfill the request.
*
* @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/501
*
* @param message - Optional message to send with the error. Default: "Service Unavailable".
* @param data - Optional data to send with the error.
*/
constructor(message = "Not Implemented", data?: TData) {
super(message, 501, data);
}
}
export class ServiceUnavailableError<TData = unknown> extends ServerError<TData> {
readonly code = "SERVICE_UNAVAILABLE";
/**
* Instantiate a new ServiceUnavailableError.
*
* The **HTTP 503 Service Unavailable** server error response status code indicates
* that the server is not ready to handle the request.
*
* This response should be used for temporary conditions and the Retry-After HTTP header
* should contain the estimated time for the recovery of the service, if possible.
*
* @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/503
*
* @param message - Optional message to send with the error. Default: "Service Unavailable".
* @param data - Optional data to send with the error.
*/
constructor(message = "Service Unavailable", data?: TData) {
super(message, 503, data);
}
}
/*
|--------------------------------------------------------------------------------
| Types
|--------------------------------------------------------------------------------
*/
export type ServerErrorJSON = {
code: ServerErrorType["code"];
status: number;
message: string;
data?: any;
};
export type ServerErrorClass<TData = unknown> = typeof ServerError<TData>;
export type ServerErrorType =
| BadRequestError
| UnauthorizedError
| ForbiddenError
| NotFoundError
| MethodNotAllowedError
| NotAcceptableError
| ConflictError
| GoneError
| UnsupportedMediaTypeError
| UnprocessableContentError
| NotImplementedError
| ServiceUnavailableError
| ValidationError
| InternalServerError;
export type ErrorSource = "body" | "query" | "params" | "client";
type ValidationErrorData = {
details: ValidationErrorDetail[];
};
type ValidationErrorDetail = {
source: ErrorSource;
code: string;
field: string;
message: string;
};

242
platform/relay/libraries/procedure.ts Normal file
View File

@@ -0,0 +1,242 @@
import type z from "zod";
import type { ZodType } from "zod";
import type { ServerContext } from "./context.ts";
import type { ServerError, ServerErrorClass } from "./errors.ts";
import type { RouteAccess } from "./route.ts";
export class Procedure<const TState extends State = State> {
readonly type = "procedure" as const;
declare readonly $params: TState["params"] extends ZodType ? z.input<TState["params"]> : never;
declare readonly $response: TState["response"] extends ZodType ? z.output<TState["response"]> : never;
/**
* Instantiate a new Procedure instance.
*
* @param state - Procedure state.
*/
constructor(readonly state: TState) {}
/**
* Procedure method value.
*/
get method(): State["method"] {
return this.state.method;
}
/**
* Access level of the procedure which acts as the first barrier of entry
* to ensure that requests are valid.
*
* By default on the server the lack of access definition will result
* in an error as all procedures needs an access definition.
*
* @param access - Access level of the procedure.
*
* @examples
*
* ```ts
* procedure
* .method("users:create")
* .access("public")
* .handle(async () => {
* // ...
* });
*
* procedure
* .method("users:get-by-id")
* .access("session")
* .params(z.string())
* .handle(async (userId, context) => {
* if (userId !== context.session.userId) {
* return new ForbiddenError("Cannot read other users details.");
* }
* });
*
* procedure
* .method("users:update")
* .access([resource("users", "update")])
* .params(z.array(z.string(), z.object({ name: z.string() })))
* .handle(async ([userId, payload], context) => {
* if (userId !== context.session.userId) {
* return new ForbiddenError("Cannot update other users details.");
* }
* console.log(userId, payload); // => string, { name: string }
* });
* ```
*/
access<TAccess extends RouteAccess>(access: TAccess): Procedure<Omit<TState, "access"> & { access: TAccess }> {
return new Procedure({ ...this.state, access: access as TAccess });
}
/**
* Defines the payload forwarded to the handler.
*
* @param params - Method payload.
*
* @examples
*
* ```ts
* procedure
* .method("users:create")
* .access([resource("users", "create")])
* .params(z.object({
* name: z.string(),
* email: z.email(),
* }))
* .handle(async ({ name, email }, context) => {
* return { name, email, createdBy: context.session.userId };
* });
* ```
*/
params<TParams extends ZodType>(params: TParams): Procedure<Omit<TState, "params"> & { params: TParams }> {
return new Procedure({ ...this.state, params });
}
/**
* Instances of the possible error responses this procedure produces.
*
* @param errors - Error shapes of the procedure.
*
* @examples
*
* ```ts
* procedure
* .method("users:list")
* .errors([
* BadRequestError
* ])
* .handle(async () => {
* return new BadRequestError();
* });
* ```
*/
errors<TErrors extends ServerErrorClass[]>(errors: TErrors): Procedure<Omit<TState, "errors"> & { errors: TErrors }> {
return new Procedure({ ...this.state, errors });
}
/**
* Shape of the success response this procedure produces. This is used by the transform
* tools to ensure the client receives parsed data.
*
* @param response - Response shape of the procedure.
*
* @examples
*
* ```ts
* procedure
* .post("users:list")
* .response(
* z.array(
* z.object({
* name: z.string()
* }),
* )
* )
* .handle(async () => {
* return [{ name: "John Doe" }];
* });
* ```
*/
response<TResponse extends ZodType>(
response: TResponse,
): Procedure<Omit<TState, "response"> & { response: TResponse }> {
return new Procedure({ ...this.state, response });
}
/**
* Server handler callback method.
*
* Handler receives the params, query, body, actions in order of definition.
* So if your route has params, and body the route handle method will
* receive (params, body) as arguments.
*
* @param handle - Handle function to trigger when the route is executed.
*
* @examples
*
* ```ts
* procedure
* .method("users:list")
* .response(
* z.array(
* z.object({
* name: z.string()
* }),
* )
* )
* .handle(async () => {
* return [{ name: "John Doe" }];
* });
* ```
*/
handle<THandleFn extends HandleFn<ServerArgs<TState>, TState["response"]>>(
handle: THandleFn,
): Procedure<Omit<TState, "handle"> & { handle: THandleFn }> {
return new Procedure({ ...this.state, handle });
}
}
/*
|--------------------------------------------------------------------------------
| Factories
|--------------------------------------------------------------------------------
*/
/**
* Route factories allowing for easy generation of relay compliant routes.
*/
export const procedure: {
/**
* Create a new procedure with given method name.
*
* @param method Name of the procedure used to match requests against.
*
* @examples
*
* ```ts
* procedure
* .method("users:get-by-id")
* .params(
* z.string().describe("Users unique identifier")
* );
* ```
*/
method<TMethod extends string>(method: TMethod): Procedure<{ method: TMethod }>;
} = {
method<TMethod extends string>(method: TMethod) {
return new Procedure({ method });
},
};
/*
|--------------------------------------------------------------------------------
| Types
|--------------------------------------------------------------------------------
*/
export type Procedures = {
[key: string]: Procedures | Procedure;
};
type State = {
method: string;
access?: RouteAccess;
params?: ZodType;
errors?: ServerErrorClass[];
response?: ZodType;
handle?: HandleFn;
};
type HandleFn<TArgs extends Array<any> = any[], TResponse = any> = (
...args: TArgs
) => TResponse extends ZodType
? Promise<z.infer<TResponse> | Response | ServerError>
: Promise<Response | ServerError | void>;
type ServerArgs<TState extends State> = HasInputArgs<TState> extends true
? [z.output<TState["params"]>, ServerContext]
: [ServerContext];
type HasInputArgs<TState extends State> = TState["params"] extends ZodType ? true : false;

469
platform/relay/libraries/route.ts Normal file
View File

@@ -0,0 +1,469 @@
import { type MatchFunction, match } from "path-to-regexp";
import z, { type ZodObject, type ZodRawShape, type ZodType } from "zod";
import type { ServerContext } from "./context.ts";
import { ServerError, type ServerErrorClass } from "./errors.ts";
export class Route<const TState extends RouteState = RouteState> {
readonly type = "route" as const;
declare readonly $params: TState["params"] extends ZodObject ? z.input<TState["params"]> : never;
declare readonly $query: TState["query"] extends ZodObject ? z.input<TState["query"]> : never;
declare readonly $body: TState["body"] extends ZodType ? z.input<TState["body"]> : never;
declare readonly $response: TState["response"] extends ZodType ? z.output<TState["response"]> : never;
#matchFn?: MatchFunction<any>;
/**
* Instantiate a new Route instance.
*
* @param state - Route state.
*/
constructor(readonly state: TState) {}
/**
* HTTP Method
*/
get method(): RouteMethod {
return this.state.method;
}
/**
* URL pattern of the route.
*/
get matchFn(): MatchFunction<any> {
if (this.#matchFn === undefined) {
this.#matchFn = match(this.path);
}
return this.#matchFn;
}
/**
* URL path
*/
get path(): string {
return this.state.path;
}
/**
* Check if the provided URL matches the route pattern.
*
* @param url - HTTP request.url
*/
match(url: string): boolean {
return this.matchFn(url) !== false;
}
/**
* Extract parameters from the provided URL based on the route pattern.
*
* @param url - HTTP request.url
*/
getParsedParams<TParams = TState["params"] extends ZodObject ? z.infer<TState["params"]> : object>(
url: string,
): TParams {
const result = match(this.path)(url);
if (result === false) {
return {} as TParams;
}
return result.params as TParams;
}
/**
* Set the meta data for this route which can be used in e.g. OpenAPI generation
*
* @param meta - Meta object
*
* @examples
*
* ```ts
* route.post("/foo").meta({ description: "Super route" });
* ```
*/
meta<TRouteMeta extends RouteMeta>(meta: TRouteMeta): Route<Prettify<Omit<TState, "meta"> & { meta: TRouteMeta }>> {
return new Route({ ...this.state, meta });
}
/**
* Access level of the route which acts as the first barrier of entry
* to ensure that requests are valid.
*
* By default on the server the lack of access definition will result
* in an error as all routes needs an access definition.
*
* @param access - Access level of the route.
*
* @examples
*
* ```ts
* const hasFooBar = action
* .make("hasFooBar")
* .response(z.object({ foobar: z.number() }))
* .handle(async () => {
* return {
* foobar: 1,
* };
* });
*
* // ### Public Endpoint
*
* route
* .post("/foo")
* .access("public")
* .handle(async ({ foobar }) => {
* console.log(typeof foobar); // => number
* });
*
* // ### Require Session
*
* route
* .post("/foo")
* .access("session")
* .handle(async ({ foobar }) => {
* console.log(typeof foobar); // => number
* });
*
* // ### Require Session & Resource Assignment
*
* route
* .post("/foo")
* .access([resource("foo", "create")])
* .handle(async ({ foobar }) => {
* console.log(typeof foobar); // => number
* });
* ```
*/
access<TAccess extends RouteAccess>(access: TAccess): Route<Prettify<Omit<TState, "access"> & { access: TAccess }>> {
return new Route({ ...this.state, access: access as TAccess });
}
/**
* Params allows for custom casting of URL parameters. If a parameter does not
* have a corresponding zod schema the default param type is "string".
*
* @param params - URL params.
*
* @examples
*
* ```ts
* route
* .post("/foo/:bar")
* .params({
* bar: z.coerce.number()
* })
* .handle(async ({ bar }) => {
* console.log(typeof bar); // => number
* });
* ```
*/
params<TParams extends ZodRawShape>(
params: TParams,
): Route<Prettify<Omit<TState, "params"> & { params: ZodObject<TParams> }>> {
return new Route({ ...this.state, params: z.object(params) as any });
}
/**
* Search allows for custom casting of URL query parameters. If a parameter does
* not have a corresponding zod schema the default param type is "string".
*
* @param query - URL query arguments.
*
* @examples
*
* ```ts
* route
* .post("/foo")
* .query({
* bar: z.number({ coerce: true })
* })
* .handle(async ({ bar }) => {
* console.log(typeof bar); // => number
* });
* ```
*/
query<TQuery extends ZodRawShape>(
query: TQuery,
): Route<Prettify<Omit<TState, "search"> & { query: ZodObject<TQuery> }>> {
return new Route({ ...this.state, query: z.object(query) as any });
}
/**
* Shape of the body this route expects to receive. This is used by all
* mutator routes and has no effect when defined on "GET" methods.
*
* @param body - Body the route expects.
*
* @examples
*
* ```ts
* route
* .post("/foo")
* .body(
* z.object({
* bar: z.number()
* })
* )
* .handle(async ({ body: { bar } }) => {
* console.log(typeof bar); // => number
* });
* ```
*/
body<TBody extends ZodType>(body: TBody): Route<Prettify<Omit<TState, "body"> & { body: TBody }>> {
return new Route({ ...this.state, body });
}
/**
* Instances of the possible error responses this route produces.
*
* @param errors - Error shapes of the route.
*
* @examples
*
* ```ts
* route
* .post("/foo")
* .errors([
* BadRequestError
* ])
* .handle(async () => {
* return new BadRequestError();
* });
* ```
*/
errors<TErrors extends ServerErrorClass[]>(
errors: TErrors,
): Route<Prettify<Omit<TState, "errors"> & { errors: TErrors }>> {
return new Route({ ...this.state, errors });
}
/**
* Shape of the success response this route produces. This is used by the transform
* tools to ensure the client receives parsed data.
*
* @param response - Response shape of the route.
*
* @examples
*
* ```ts
* route
* .post("/foo")
* .response(
* z.object({
* bar: z.number()
* })
* )
* .handle(async () => {
* return {
* bar: 1
* }
* });
* ```
*/
response<TResponse extends ZodType>(
response: TResponse,
): Route<Prettify<Omit<TState, "response"> & { response: TResponse }>> {
return new Route({ ...this.state, response });
}
/**
* Server handler callback method.
*
* Handler receives the params, query, body, actions in order of definition.
* So if your route has params, and body the route handle method will
* receive (params, body) as arguments.
*
* @param handle - Handle function to trigger when the route is executed.
*
* @examples
*
* ```ts
* relay
* .post("/api/v1/foo/:bar")
* .params({ bar: z.string() })
* .body(z.tuple([z.string(), z.number()]))
* .handle(async ({ bar }, [ "string", number ]) => {});
* ```
*/
handle<THandleFn extends HandleFn<ServerArgs<TState>, TState["response"]>>(
handle: THandleFn,
): Route<Omit<TState, "handle"> & { handle: THandleFn }> {
return new Route({ ...this.state, handle });
}
}
/*
|--------------------------------------------------------------------------------
| Factories
|--------------------------------------------------------------------------------
*/
/**
* Route factories allowing for easy generation of relay compliant routes.
*/
export const route: {
post<TPath extends string>(
path: TPath,
): Route<{ method: "POST"; path: TPath; content: "json"; errors: [ServerErrorClass] }>;
get<TPath extends string>(
path: TPath,
): Route<{ method: "GET"; path: TPath; content: "json"; errors: [ServerErrorClass] }>;
put<TPath extends string>(
path: TPath,
): Route<{ method: "PUT"; path: TPath; content: "json"; errors: [ServerErrorClass] }>;
patch<TPath extends string>(
path: TPath,
): Route<{ method: "PATCH"; path: TPath; content: "json"; errors: [ServerErrorClass] }>;
delete<TPath extends string>(
path: TPath,
): Route<{ method: "DELETE"; path: TPath; content: "json"; errors: [ServerErrorClass] }>;
} = {
/**
* Create a new "POST" route for the given path.
*
* @param path - Path to generate route for.
*
* @examples
*
* ```ts
* route
* .post("/foo")
* .body(
* z.object({ bar: z.string() })
* );
* ```
*/
post<TPath extends string>(path: TPath) {
return new Route({ method: "POST", path, content: "json", errors: [ServerError] });
},
/**
* Create a new "GET" route for the given path.
*
* @param path - Path to generate route for.
*
* @examples
*
* ```ts
* route.get("/foo");
* ```
*/
get<TPath extends string>(path: TPath) {
return new Route({ method: "GET", path, content: "json", errors: [ServerError] });
},
/**
* Create a new "PUT" route for the given path.
*
* @param path - Path to generate route for.
*
* @examples
*
* ```ts
* route
* .put("/foo")
* .body(
* z.object({ bar: z.string() })
* );
* ```
*/
put<TPath extends string>(path: TPath) {
return new Route({ method: "PUT", path, content: "json", errors: [ServerError] });
},
/**
* Create a new "PATCH" route for the given path.
*
* @param path - Path to generate route for.
*
* @examples
*
* ```ts
* route
* .patch("/foo")
* .body(
* z.object({ bar: z.string() })
* );
* ```
*/
patch<TPath extends string>(path: TPath) {
return new Route({ method: "PATCH", path, content: "json", errors: [ServerError] });
},
/**
* Create a new "DELETE" route for the given path.
*
* @param path - Path to generate route for.
*
* @examples
*
* ```ts
* route.delete("/foo");
* ```
*/
delete<TPath extends string>(path: TPath) {
return new Route({ method: "DELETE", path, content: "json", errors: [ServerError] });
},
};
/*
|--------------------------------------------------------------------------------
| Types
|--------------------------------------------------------------------------------
*/
export type Routes = {
[key: string]: Routes | Route | RouteFn;
};
export type RouteFn = (...args: any[]) => any;
type RouteState = {
method: RouteMethod;
path: string;
meta?: RouteMeta;
access?: RouteAccess;
params?: ZodObject;
query?: ZodObject;
body?: ZodType;
errors: ServerErrorClass[];
response?: ZodType;
handle?: HandleFn;
};
export type RouteMeta = {
openapi?: "internal" | "external";
description?: string;
summary?: string;
tags?: string[];
} & Record<string, unknown>;
export type RouteMethod = "POST" | "GET" | "PUT" | "PATCH" | "DELETE";
export type RouteAccess = "public" | "authenticated";
type HandleFn<TArgs extends Array<any> = any[], TResponse = any> = (
...args: TArgs
) => TResponse extends ZodType
? Promise<z.infer<TResponse> | Response | ServerError>
: Promise<Response | ServerError | void>;
type ServerArgs<TState extends RouteState> = HasInputArgs<TState> extends true
? [
(TState["params"] extends ZodObject ? { params: z.output<TState["params"]> } : unknown) &
(TState["query"] extends ZodObject ? { query: z.output<TState["query"]> } : unknown) &
(TState["body"] extends ZodType ? { body: z.output<TState["body"]> } : unknown),
ServerContext,
]
: [ServerContext];
type HasInputArgs<TState extends RouteState> = TState["params"] extends ZodObject
? true
: TState["query"] extends ZodObject
? true
: TState["body"] extends ZodType
? true
: false;
type Prettify<T> = {
[K in keyof T]: T[K];
} & {};

7
platform/relay/mod.ts Normal file
View File

@@ -0,0 +1,7 @@
export * from "./adapters/http.ts";
export * from "./libraries/adapter.ts";
export * from "./libraries/client.ts";
export * from "./libraries/context.ts";
export * from "./libraries/errors.ts";
export * from "./libraries/procedure.ts";
export * from "./libraries/route.ts";

17
platform/relay/package.json Normal file
View File

@@ -0,0 +1,17 @@
{
"name": "@platform/relay",
"version": "0.0.0",
"private": true,
"type": "module",
"main": "./mod.ts",
"exports": {
".": "./mod.ts"
},
"dependencies": {
"@platform/auth": "workspace:*",
"@platform/socket": "workspace:*",
"@platform/supertokens": "workspace:*",
"path-to-regexp": "8",
"zod": "4.1.12"
}
}