chore(rivetkit): add WebSocketContext and RequestContext

Author: NathanFlurry

rivetkit-typescript/packages/rivetkit/fixtures/driver-test-suite/raw-http-request-properties.ts

@@ -1,9 +1,9 @@
-import { type ActorContext, actor } from "rivetkit";
+import { actor, type RequestContext } from "rivetkit";
 
 export const rawHttpRequestPropertiesActor = actor({
 	actions: {},
 	onRequest(
-		ctx: ActorContext<any, any, any, any, any, any>,
+		ctx: RequestContext<any, any, any, any, any, any>,
 		request: Request,
 	) {
 		// Extract all relevant Request properties

rivetkit-typescript/packages/rivetkit/fixtures/driver-test-suite/raw-http.ts

@@ -1,12 +1,12 @@
 import { Hono } from "hono";
-import { type ActorContext, actor } from "rivetkit";
+import { actor, type RequestContext } from "rivetkit";
 
 export const rawHttpActor = actor({
 	state: {
 		requestCount: 0,
 	},
 	onRequest(
-		ctx: ActorContext<any, any, any, any, any, any>,
+		ctx: RequestContext<any, any, any, any, any, any>,
 		request: Request,
 	) {
 		const url = new URL(request.url);
@@ -111,7 +111,7 @@ export const rawHttpHonoActor = actor({
 		return { router };
 	},
 	onRequest(
-		ctx: ActorContext<any, any, any, any, any, any>,
+		ctx: RequestContext<any, any, any, any, any, any>,
 		request: Request,
 	) {
 		// Use the Hono router from vars

rivetkit-typescript/packages/rivetkit/src/actor/config.ts

@@ -3,6 +3,8 @@ import type { UniversalWebSocket } from "@/common/websocket-interface";
 import type { Conn } from "./conn/mod";
 import type { ActionContext } from "./contexts/action";
 import type { ActorContext } from "./contexts/actor";
+import type { RequestContext } from "./contexts/request";
+import type { WebSocketContext } from "./contexts/websocket";
 import type { AnyDatabaseProvider } from "./database";
 
 export type InitContext = ActorContext<
@@ -407,11 +409,13 @@ interface BaseActorConfig<
 	 * This handler receives raw HTTP requests made to `/actors/{actorName}/http/*` endpoints.
 	 * Use this hook to handle custom HTTP patterns, REST APIs, or other HTTP-based protocols.
 	 *
+	 * @param c The request context with access to the connection
 	 * @param request The raw HTTP request object
+	 * @param opts Additional options
 	 * @returns A Response object to send back, or void to continue with default routing
 	 */
 	onRequest?: (
-		c: ActorContext<
+		c: RequestContext<
 			TState,
 			TConnParams,
 			TConnState,
@@ -420,7 +424,6 @@ interface BaseActorConfig<
 			TDatabase
 		>,
 		request: Request,
-		opts: {},
 	) => Response | Promise<Response>;
 
 	/**
@@ -429,11 +432,12 @@ interface BaseActorConfig<
 	 * This handler receives WebSocket connections made to `/actors/{actorName}/websocket/*` endpoints.
 	 * Use this hook to handle custom WebSocket protocols, binary streams, or other WebSocket-based communication.
 	 *
+	 * @param c The WebSocket context with access to the connection
 	 * @param websocket The raw WebSocket connection
-	 * @param request The original HTTP upgrade request
+	 * @param opts Additional options including the original HTTP upgrade request
 	 */
 	onWebSocket?: (
-		c: ActorContext<
+		c: WebSocketContext<
 			TState,
 			TConnParams,
 			TConnState,

rivetkit-typescript/packages/rivetkit/src/actor/contexts/request.ts

@@ -0,0 +1,183 @@
+import type { ActorKey } from "@/actor/mod";
+import type { Client } from "@/client/client";
+import type { Logger } from "@/common/log";
+import type { Registry } from "@/registry/mod";
+import type { Conn, ConnId } from "../conn/mod";
+import type { AnyDatabaseProvider, InferDatabaseClient } from "../database";
+import type { SaveStateOptions } from "../instance/state-manager";
+import type { Schedule } from "../schedule";
+import type { ActorContext } from "./actor";
+
+/**
+ * Context for raw HTTP request handlers (onRequest).
+ *
+ * @typeParam TState - The actor state type
+ * @typeParam TConnParams - The connection parameters type
+ * @typeParam TConnState - The connection state type
+ * @typeParam TVars - The actor variables type
+ * @typeParam TInput - The actor input type
+ * @typeParam TDatabase - The database provider type
+ */
+export class RequestContext<
+	TState,
+	TConnParams,
+	TConnState,
+	TVars,
+	TInput,
+	TDatabase extends AnyDatabaseProvider,
+> {
+	#actorContext: ActorContext<
+		TState,
+		TConnParams,
+		TConnState,
+		TVars,
+		TInput,
+		TDatabase
+	>;
+
+	/**
+	 * Should not be called directly.
+	 *
+	 * @param actorContext - The actor context
+	 * @param conn - The connection associated with the request
+	 */
+	constructor(
+		actorContext: ActorContext<
+			TState,
+			TConnParams,
+			TConnState,
+			TVars,
+			TInput,
+			TDatabase
+		>,
+		public readonly conn: Conn<
+			TState,
+			TConnParams,
+			TConnState,
+			TVars,
+			TInput,
+			TDatabase
+		>,
+	) {
+		this.#actorContext = actorContext;
+	}
+
+	/**
+	 * Get the actor state
+	 */
+	get state(): TState {
+		return this.#actorContext.state;
+	}
+
+	/**
+	 * Get the actor variables
+	 */
+	get vars(): TVars {
+		return this.#actorContext.vars;
+	}
+
+	/**
+	 * Broadcasts an event to all connected clients.
+	 */
+	broadcast(name: string, ...args: any[]): void {
+		this.#actorContext.broadcast(name, ...args);
+	}
+
+	/**
+	 * Gets the logger instance.
+	 */
+	get log(): Logger {
+		return this.#actorContext.log;
+	}
+
+	/**
+	 * Gets actor ID.
+	 */
+	get actorId(): string {
+		return this.#actorContext.actorId;
+	}
+
+	/**
+	 * Gets the actor name.
+	 */
+	get name(): string {
+		return this.#actorContext.name;
+	}
+
+	/**
+	 * Gets the actor key.
+	 */
+	get key(): ActorKey {
+		return this.#actorContext.key;
+	}
+
+	/**
+	 * Gets the region.
+	 */
+	get region(): string {
+		return this.#actorContext.region;
+	}
+
+	/**
+	 * Gets the scheduler.
+	 */
+	get schedule(): Schedule {
+		return this.#actorContext.schedule;
+	}
+
+	/**
+	 * Gets the map of connections.
+	 */
+	get conns(): Map<
+		ConnId,
+		Conn<TState, TConnParams, TConnState, TVars, TInput, TDatabase>
+	> {
+		return this.#actorContext.conns;
+	}
+
+	/**
+	 * Returns the client for the given registry.
+	 */
+	client<R extends Registry<any>>(): Client<R> {
+		return this.#actorContext.client<R>();
+	}
+
+	/**
+	 * @experimental
+	 */
+	get db(): InferDatabaseClient<TDatabase> {
+		return this.#actorContext.db;
+	}
+
+	/**
+	 * Forces the state to get saved.
+	 */
+	async saveState(opts: SaveStateOptions): Promise<void> {
+		return this.#actorContext.saveState(opts);
+	}
+
+	/**
+	 * Prevents the actor from sleeping until promise is complete.
+	 */
+	waitUntil(promise: Promise<void>): void {
+		this.#actorContext.waitUntil(promise);
+	}
+
+	/**
+	 * AbortSignal that fires when the actor is stopping.
+	 */
+	get abortSignal(): AbortSignal {
+		return this.#actorContext.abortSignal;
+	}
+
+	/**
+	 * Forces the actor to sleep.
+	 *
+	 * Not supported on all drivers.
+	 *
+	 * @experimental
+	 */
+	sleep() {
+		this.#actorContext.sleep();
+	}
+}