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

feat: add procedure to relay

Browse Source
This commit is contained in:
Christoffer Rødvik
2025-08-18 01:05:23 +02:00
parent 81108e0a60
commit d322138502
12 changed files with 346 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files

33
api/libraries/server/context.ts
View File

@@ -1,4 +1,6 @@
import { ServerContext, UnauthorizedError } from "@spec/relay";
import { ServerContext } from "@spec/relay";
import type { Sockets } from "~libraries/socket/sockets.ts";
import { Session } from "../auth/auth.ts";
import { req } from "./request.ts";
@@ -11,15 +13,25 @@ declare module "@spec/relay" {
request: Request;
/**
* Get request session instance.
* Is the request authenticated.
*/
session: Session;
isAuthenticated: boolean;
/**
* Get account id from session, throws an error if the request
* does not have a valid session.
*/
accountId: string;
/**
* Get request session instance.
*/
session: Session;
/**
* Sockets instance attached to the server.
*/
sockets: Sockets;
}
}
@@ -27,15 +39,20 @@ export function getRequestContext(request: Request): ServerContext {
return {
request,
get session(): Session {
if (req.session === undefined) {
throw new UnauthorizedError();
}
return req.session;
get isAuthenticated(): boolean {
return req.isAuthenticated;
},
get accountId() {
return this.session.accountId;
},
get session(): Session {
return req.session;
},
get sockets(): Sockets {
return req.sockets;
},
};
}

42
api/libraries/server/request.ts
View File

@@ -1,3 +1,5 @@
import { InternalServerError, UnauthorizedError } from "@spec/relay";
import { Session } from "../auth/auth.ts";
import { asyncLocalStorage } from "./storage.ts";
@@ -5,21 +7,16 @@ export const req = {
get store() {
const store = asyncLocalStorage.getStore();
if (store === undefined) {
throw new Error("Request > AsyncLocalStorage not defined.");
throw new InternalServerError("AsyncLocalStorage not defined.");
}
return store;
},
get socket() {
return this.store.socket;
},
/**
* Get store that is potentially undefined.
* Typically used when utility functions might run in and out of request scope.
*/
get unsafeStore() {
return asyncLocalStorage.getStore();
get sockets() {
if (this.store.sockets === undefined) {
throw new InternalServerError("Sockets not defined.");
}
return this.store.sockets;
},
/**
@@ -32,7 +29,10 @@ export const req = {
/**
* Get current session.
*/
get session(): Session | undefined {
get session(): Session {
if (this.store.session === undefined) {
throw new UnauthorizedError();
}
return this.store.session;
},
@@ -44,14 +44,18 @@ export const req = {
},
/**
* Sends a JSON-RPC 2.0 notification to the request if sent through a
* WebSocket connection.
*
* @param method - Method to send notification to.
* @param params - Params to pass to the method.
* Get current session.
*/
notify(method: string, params: any): void {
this.socket?.send(JSON.stringify({ jsonrpc: "2.0", method, params }));
getSession(): Session | undefined {
return this.store.session;
},
/**
* Get store that is potentially undefined.
* Typically used when utility functions might run in and out of request scope.
*/
getStore() {
return asyncLocalStorage.getStore();
},
} as const;

3
api/libraries/server/storage.ts
View File

@@ -1,6 +1,7 @@
import { AsyncLocalStorage } from "node:async_hooks";
import type { Session } from "~libraries/auth/mod.ts";
import type { Sockets } from "~libraries/socket/sockets.ts";
export const asyncLocalStorage = new AsyncLocalStorage<{
session?: Session;
@@ -9,7 +10,7 @@ export const asyncLocalStorage = new AsyncLocalStorage<{
start: number;
end?: number;
};
socket?: WebSocket;
sockets?: Sockets;
response: {
headers: Headers;
};

1
api/libraries/socket/mod.ts
View File

@@ -1 +0,0 @@
export { Sockets } from "./sockets.ts";

33
api/libraries/socket/upgrade.ts
View File

@@ -2,6 +2,7 @@ import { toJsonRpc } from "@valkyr/json-rpc";
import { Session } from "~libraries/auth/mod.ts";
import { logger } from "~libraries/logger/mod.ts";
import { asyncLocalStorage } from "~libraries/server/storage.ts";
import { sockets } from "./sockets.ts";
@@ -23,35 +24,35 @@ export function upgrade(request: Request, session?: Session) {
return;
}
const body = toJsonRpc(event.data);
const message = toJsonRpc(event.data);
logger.prefix("Socket").info(body);
logger.prefix("Socket").info(message);
asyncLocalStorage.run(
{
session,
info: {
method: body.method!,
method: message.method!,
start: Date.now(),
},
socket,
sockets,
response: {
headers: new Headers(),
},
},
async () => {
api
.handleCommand(body)
.then((response) => {
if (response !== undefined) {
logger.info({ response });
socket.send(JSON.stringify(response));
}
})
.catch((error) => {
logger.info({ error });
socket.send(JSON.stringify(error));
});
// api
// .send(body)
// .then((response) => {
// if (response !== undefined) {
// logger.info({ response });
// socket.send(JSON.stringify(response));
// }
// })
// .catch((error) => {
// logger.info({ error });
// socket.send(JSON.stringify(error));
// });
},
);
});

1
api/package.json
View File

@@ -16,6 +16,7 @@
"@valkyr/auth": "npm:@jsr/valkyr__auth@2",
"@valkyr/event-store": "npm:@jsr/valkyr__event-store@2.0.0-beta.6",
"@valkyr/inverse": "npm:@jsr/valkyr__inverse@1",
"@valkyr/json-rpc": "npm:@jsr/valkyr__json-rpc@1",
"cookie": "1",
"mongodb": "6",
"zod": "4"

22
api/procedures/event.ts Normal file
View File

@@ -0,0 +1,22 @@
import { procedure } from "@spec/relay/mod.ts";
import z from "zod";
const EventSchema = z.object({
id: z.uuid(),
stream: z.uuid(),
type: z.string(),
data: z.any(),
meta: z.any(),
recorded: z.string(),
created: z.string(),
});
export default procedure
.method("event")
.access("public")
.params(EventSchema)
.response(z.uuid())
.handle(async (event) => {
console.log(event);
return crypto.randomUUID();
});

9
deno.lock generated
View File

@@ -14,6 +14,7 @@
"npm:@jsr/valkyr__event-emitter@1": "1.0.1",
"npm:@jsr/valkyr__event-store@2.0.0-beta.6": "2.0.0-beta.6",
"npm:@jsr/valkyr__inverse@1": "1.0.1",
"npm:@jsr/valkyr__json-rpc@1": "1.1.0",
"npm:@tailwindcss/vite@4": "4.1.12_vite@7.1.2__picomatch@4.0.3_@types+node@22.15.15",
"npm:@tanstack/react-query@5": "5.85.3_react@19.1.1",
"npm:@tanstack/react-router-devtools@1": "1.131.18_@tanstack+react-router@1.131.18__react@19.1.1__react-dom@19.1.1___react@19.1.1_react@19.1.1_react-dom@19.1.1__react@19.1.1",
@@ -567,6 +568,13 @@
"integrity": "sha512-uZpzPct9FGobgl6H+iR3VJlzZbTFVmJSrB4z5In8zHgIJCkmgYj0diU3soU6MuiKR7SFBfD4PGSuUpTTJHNMlg==",
"tarball": "https://npm.jsr.io/~/11/@jsr/valkyr__inverse/1.0.1.tgz"
},
"@jsr/valkyr__json-rpc@1.1.0": {
"integrity": "sha512-i1dwWLI29i5mqRvS2NbI3jUyw8uZuO71hJRvT5+sGAexG8RmQJP4N+ETJkxq0RNwNAGGG1bocuzdqnawa2ahIA==",
"dependencies": [
"@jsr/valkyr__event-emitter"
],
"tarball": "https://npm.jsr.io/~/11/@jsr/valkyr__json-rpc/1.1.0.tgz"
},
"@jsr/valkyr__testcontainers@2.0.2": {
"integrity": "sha512-YnmfraYFr3msoUGrIFeElm03nbQqXOaPu0QUT6JI3w6/mIYpVfzPxghkB7gn2RIc81QgrqjwKJE/AL3dltlR1w==",
"dependencies": [
@@ -2136,6 +2144,7 @@
"npm:@jsr/valkyr__auth@2",
"npm:@jsr/valkyr__event-store@2.0.0-beta.6",
"npm:@jsr/valkyr__inverse@1",
"npm:@jsr/valkyr__json-rpc@1",
"npm:cookie@1",
"npm:mongodb@6",
"npm:zod@4"

239
spec/relay/libraries/procedure.ts Normal file
View File

@@ -0,0 +1,239 @@
import z, { ZodType } from "zod";
import { ServerError, ServerErrorClass } from "./errors.ts";
import { Access, ServerContext } from "./types.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 Access>(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?: Access;
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;

4
spec/relay/libraries/route.ts
View File

@@ -3,6 +3,7 @@ import z, { ZodObject, ZodRawShape, ZodType } from "zod";
import { ServerError, ServerErrorClass } from "./errors.ts";
import { Hooks } from "./hooks.ts";
import { ServerContext } from "./types.ts";
export class Route<const TState extends RouteState = RouteState> {
readonly type = "route" as const;
@@ -447,9 +448,6 @@ export type RouteAccess = "public" | "session" | (() => boolean)[];
export type AccessFn = (resource: string, action: string) => () => boolean;
// eslint-disable-next-line @typescript-eslint/no-empty-object-type
export interface ServerContext {}
type HandleFn<TArgs extends Array<any> = any[], TResponse = any> = (
...args: TArgs
) => TResponse extends ZodType

6
spec/relay/libraries/types.ts Normal file
View File

@@ -0,0 +1,6 @@
export type Access = "public" | "session" | (() => boolean)[];
export type AccessFn = (resource: string, action: string) => () => boolean;
// eslint-disable-next-line @typescript-eslint/no-empty-object-type
export interface ServerContext {}

1
spec/relay/mod.ts
View File

@@ -2,4 +2,5 @@ export * from "./libraries/adapter.ts";
export * from "./libraries/client.ts";
export * from "./libraries/errors.ts";
export * from "./libraries/hooks.ts";
export * from "./libraries/procedure.ts";
export * from "./libraries/route.ts";