@pluv/platform-cloudflare 0.0.0-experimental-20250527040415

package/src/CloudflarePlatform.ts

@@ -0,0 +1,209 @@
+import type {
+    AbstractPlatformConfig,
+    ConvertWebSocketConfig,
+    WebSocketRegistrationMode,
+    WebSocketSerializedState,
+} from "@pluv/io";
+import { AbstractPlatform } from "@pluv/io";
+import { PersistenceCloudflareTransactionalStorage } from "@pluv/persistence-cloudflare-transactional-storage";
+import type { IOAuthorize, Json } from "@pluv/types";
+import { CloudflareWebSocket } from "./CloudflareWebSocket";
+import { DEFAULT_REGISTRATION_MODE } from "./constants";
+
+export type CloudflarePlatformRoomContext<
+    TEnv extends Record<string, any>,
+    TMeta extends Record<string, Json>,
+> = {
+    env: TEnv;
+    state: DurableObjectState;
+} & (keyof TMeta extends never ? { meta?: undefined } : { meta: TMeta });
+
+export type CloudflarePlatformConfig<
+    TEnv extends Record<string, any> = {},
+    TMeta extends Record<string, Json> = {},
+> = AbstractPlatformConfig<CloudflarePlatformRoomContext<TEnv, TMeta>> & {
+    mode?: WebSocketRegistrationMode;
+};
+
+export class CloudflarePlatform<
+    TAuthorize extends IOAuthorize<any, any> | null = null,
+    TEnv extends Record<string, any> = {},
+    TMeta extends Record<string, Json> = {},
+> extends AbstractPlatform<
+    CloudflareWebSocket<TAuthorize>,
+    { env: TEnv; request: Request },
+    CloudflarePlatformRoomContext<TEnv, TMeta>,
+    {
+        authorize: {
+            secret: true;
+        };
+        handleMode: "io";
+        requireAuth: false;
+        registrationMode: WebSocketRegistrationMode;
+        listeners: {
+            onRoomDeleted: true;
+            onRoomMessage: true;
+            onStorageUpdated: true;
+            onUserConnected: true;
+            onUserDisconnected: true;
+        };
+        router: true;
+    }
+> {
+    public readonly id = crypto.randomUUID();
+    public readonly _config;
+    public readonly _name = "platformCloudflare";
+
+    constructor(config: CloudflarePlatformConfig<TEnv, TMeta>) {
+        super({
+            ...config,
+            ...(config.roomContext && config.mode === "detached"
+                ? {
+                      persistence:
+                          config.persistence ??
+                          new PersistenceCloudflareTransactionalStorage({ mode: "sqlite" }),
+                  }
+                : {}),
+        });
+
+        this._config = {
+            authorize: {
+                secret: true as const,
+            },
+            handleMode: "io" as const,
+            registrationMode: config.mode ?? DEFAULT_REGISTRATION_MODE,
+            requireAuth: false as const,
+            listeners: {
+                onRoomDeleted: true as const,
+                onRoomMessage: true as const,
+                onStorageUpdated: true as const,
+                onUserConnected: true as const,
+                onUserDisconnected: true as const,
+            },
+            router: true as const,
+        };
+
+        const detachedState = this._getDetachedState();
+
+        if (!detachedState) return;
+
+        detachedState.setWebSocketAutoResponse(
+            new WebSocketRequestResponsePair(
+                '{"type":"$ping","data":{}}',
+                JSON.stringify({ type: "$pong", data: {} }),
+            ),
+        );
+    }
+
+    public async acceptWebSocket(webSocket: CloudflareWebSocket<TAuthorize>): Promise<void> {
+        const detachedState = this._getDetachedState();
+
+        if (!detachedState) {
+            webSocket.webSocket.accept();
+
+            return;
+        }
+
+        detachedState.acceptWebSocket(webSocket.webSocket);
+    }
+
+    public convertWebSocket(
+        webSocket: WebSocket,
+        config: ConvertWebSocketConfig,
+    ): CloudflareWebSocket<TAuthorize> {
+        const { room } = config;
+
+        return new CloudflareWebSocket<TAuthorize>(webSocket, {
+            persistence: this.persistence,
+            platform: this,
+            room,
+        });
+    }
+
+    public getLastPing(webSocket: CloudflareWebSocket<TAuthorize>): number | null {
+        const detachedState = this._getDetachedState();
+
+        if (!detachedState) return null;
+
+        const timestamp = detachedState.getWebSocketAutoResponseTimestamp(webSocket.webSocket);
+
+        return timestamp?.getTime() ?? null;
+    }
+
+    public getSerializedState(webSocket: WebSocket): WebSocketSerializedState | null {
+        const deserialized = webSocket.deserializeAttachment();
+
+        return deserialized?.state ?? null;
+    }
+
+    public getSessionId(webSocket: WebSocket): string | null {
+        const deserialized = webSocket.deserializeAttachment() ?? {};
+        const sessionId = deserialized.sessionId;
+
+        if (typeof sessionId !== "string") return null;
+
+        return sessionId;
+    }
+
+    public getWebSockets(): readonly WebSocket[] {
+        const detachedState = this._getDetachedState();
+
+        if (!detachedState) return [];
+
+        const webSockets = detachedState.getWebSockets() ?? [];
+
+        return webSockets;
+    }
+
+    public initialize(
+        config: AbstractPlatformConfig<CloudflarePlatformRoomContext<TEnv, TMeta>>,
+    ): this {
+        const ctx = config.roomContext ?? { ...this._roomContext };
+
+        if (!ctx.env || !ctx.state) throw new Error("Could not derive platform roomContext");
+
+        const roomContext = {
+            env: ctx.env,
+            meta: ctx.meta,
+            state: ctx.state,
+        } as CloudflarePlatformRoomContext<TEnv, TMeta>;
+
+        return new CloudflarePlatform<TAuthorize, TEnv, TMeta>({
+            roomContext,
+            mode: this._config.registrationMode,
+            persistence: this.persistence.initialize(roomContext),
+            pubSub: this.pubSub,
+        })._initialize() as this;
+    }
+
+    public parseData(data: string | ArrayBuffer): Record<string, any> {
+        if (typeof data === "string") return JSON.parse(data);
+
+        const decoder = new TextDecoder("utf8");
+
+        return JSON.parse(decoder.decode(data));
+    }
+
+    public randomUUID(): string {
+        return crypto.randomUUID();
+    }
+
+    public setSerializedState(
+        webSocket: CloudflareWebSocket<TAuthorize>,
+        state: WebSocketSerializedState,
+    ): WebSocketSerializedState {
+        const deserialized = webSocket.webSocket.deserializeAttachment() ?? {};
+
+        webSocket.webSocket.serializeAttachment({ ...deserialized, state });
+
+        return state;
+    }
+
+    private _getDetachedState(): DurableObjectState | null {
+        if (this._config.registrationMode !== "detached") return null;
+
+        const detachedState = this._roomContext?.state ?? null;
+
+        return detachedState;
+    }
+}

package/src/CloudflareWebSocket.ts

@@ -0,0 +1,141 @@
+import type {
+    AbstractEventMap,
+    AbstractListener,
+    AbstractWebSocketConfig,
+    WebSocketSerializedState,
+    WebSocketSession,
+} from "@pluv/io";
+import { AbstractWebSocket } from "@pluv/io";
+import type { InferIOAuthorizeUser, IOAuthorize, JsonObject } from "@pluv/types";
+
+export interface CloudflareWebSocketEventMap {
+    close: CloseEvent;
+    message: MessageEvent;
+    open: Event;
+    error: ErrorEvent;
+}
+
+export type CloudflareWebSocketConfig = AbstractWebSocketConfig;
+
+export class CloudflareWebSocket<
+    TAuthorize extends IOAuthorize<any, any> | null = null,
+> extends AbstractWebSocket<WebSocket, TAuthorize> {
+    public set presence(presence: JsonObject | null) {
+        const deserialized = this.webSocket.deserializeAttachment();
+        const state = deserialized.state;
+
+        this.webSocket.serializeAttachment({
+            ...this.webSocket.deserializeAttachment(),
+            state: { ...state, presence },
+        });
+    }
+
+    public get readyState(): 0 | 1 | 2 | 3 {
+        return this.webSocket.readyState as 0 | 1 | 2 | 3;
+    }
+
+    public get session(): WebSocketSession<TAuthorize> {
+        const deserialized = this.webSocket.deserializeAttachment();
+        const sessionId = deserialized.sessionId as string;
+        const state = this.state;
+        const user = (deserialized.user ?? null) as InferIOAuthorizeUser<TAuthorize>;
+
+        return {
+            ...state,
+            id: sessionId,
+            user,
+            webSocket: this,
+        };
+    }
+
+    public get sessionId(): string {
+        const deserialized = this.webSocket.deserializeAttachment() ?? {};
+        const sessionId = deserialized.sessionId ?? `p_${crypto.randomUUID()}`;
+
+        if (typeof deserialized.sessionId !== "string") {
+            this.webSocket.serializeAttachment({ ...deserialized, sessionId });
+        }
+
+        return sessionId;
+    }
+
+    public get state(): WebSocketSerializedState {
+        const deserialized = this.webSocket.deserializeAttachment();
+        const state = deserialized?.state ?? null;
+
+        if (!state) throw new Error("Could not get websocket state");
+
+        const currentPing = state.timers.ping;
+        const lastPing = this._platform.getLastPing(this);
+
+        if (!lastPing) return state;
+        if (currentPing >= lastPing) return state;
+
+        const newState: WebSocketSerializedState = {
+            ...state,
+            timers: { ...state.timers, ping: lastPing },
+        };
+
+        return this._platform.setSerializedState(this, newState);
+    }
+
+    public set state(state: WebSocketSerializedState) {
+        const deserialized = this.webSocket.deserializeAttachment();
+
+        this.webSocket.serializeAttachment({ ...deserialized, state });
+    }
+
+    public set user(user: InferIOAuthorizeUser<TAuthorize>) {
+        const deserialized = this.webSocket.deserializeAttachment();
+
+        this.webSocket.serializeAttachment({ ...deserialized, user });
+    }
+
+    constructor(webSocket: WebSocket, config: CloudflareWebSocketConfig) {
+        const { room } = config;
+
+        super(webSocket, config);
+
+        const state: WebSocketSerializedState = {
+            presence: null,
+            quit: false,
+            room,
+            timers: {
+                ping: new Date().getTime(),
+                presence: null,
+            },
+        };
+
+        webSocket.serializeAttachment({
+            state,
+            ...webSocket.deserializeAttachment(),
+        });
+    }
+
+    public addEventListener<TType extends keyof AbstractEventMap>(
+        type: TType,
+        handler: AbstractListener<TType>,
+    ) {
+        this.webSocket.addEventListener(type, handler as any);
+    }
+
+    public close(code?: number | undefined, reason?: string | undefined): void {
+        const canClose = [this.CONNECTING, this.OPEN].some(
+            (readyState) => readyState === this.readyState,
+        );
+
+        if (!canClose) return;
+
+        this.webSocket.close(code, reason);
+    }
+
+    public send(message: string | ArrayBuffer | ArrayBufferView): void {
+        if (this.readyState !== this.OPEN) return;
+
+        this.webSocket.send(message);
+    }
+
+    public terminate(code: number = 1011): void {
+        return this.webSocket.close(code, "Terminated");
+    }
+}

package/src/constants.ts

@@ -0,0 +1,4 @@
+import type { WebSocketRegistrationMode } from "@pluv/io";
+
+export const DEFAULT_REGISTRATION_MODE: WebSocketRegistrationMode = "detached";
+export const GARBAGE_COLLECT_INTERVAL_MS = 60_000;

package/src/createPluvHandler.ts

@@ -0,0 +1,244 @@
+import type { InferInitContextType, IORoom, PluvServer } from "@pluv/io";
+import type {
+    BaseUser,
+    Id,
+    InferIOAuthorize,
+    InferIOAuthorizeUser,
+    Maybe,
+    MaybePromise,
+} from "@pluv/types";
+import { DurableObject as BaseDurableObject } from "cloudflare:workers";
+import { match } from "path-to-regexp";
+import { CloudflarePlatform } from "./CloudflarePlatform";
+import { GARBAGE_COLLECT_INTERVAL_MS } from "./constants";
+
+export type AuthorizeFunctionContext<TPluvServer extends PluvServer<any, any, any, any>> = {
+    room: string;
+} & InferInitContextType<
+    TPluvServer extends PluvServer<infer IPlatform, any, any, any> ? IPlatform : never
+>;
+export type AuthorizeFunction<TPluvServer extends PluvServer<any, any, any, any>> = (
+    ctx: AuthorizeFunctionContext<TPluvServer>,
+) => MaybePromise<Maybe<InferIOAuthorizeUser<InferIOAuthorize<TPluvServer>>>>;
+
+export type CreatePluvHandlerConfig<
+    TPluvServer extends PluvServer<any, any, any, any>,
+    TEnv extends Record<string, any>,
+> = {
+    binding: string;
+    endpoint?: string;
+    modify?: (request: Request, response: Response, env: TEnv) => MaybePromise<Response>;
+    io: TPluvServer;
+} & (InferIOAuthorizeUser<InferIOAuthorize<TPluvServer>> extends BaseUser
+    ? { authorize: AuthorizeFunction<TPluvServer> }
+    : { authorize?: undefined });
+
+export type PluvHandlerFetch<TEnv extends Record<string, any> = {}> = (
+    request: Request,
+    env: TEnv,
+) => Promise<Response | null>;
+
+export interface CreatePluvHandlerResult<TEnv extends Record<string, any> = {}> {
+    DurableObject: {
+        new (state: DurableObjectState, env: TEnv): BaseDurableObject<TEnv>;
+    };
+    fetch: PluvHandlerFetch<TEnv>;
+    handler: ExportedHandler<TEnv>;
+}
+
+type InferCloudflarePluvHandlerEnv<
+    TPluvServer extends PluvServer<CloudflarePlatform<any, any>, any, any, any>,
+> = TPluvServer extends PluvServer<CloudflarePlatform<any, infer IEnv>, any, any, any> ? IEnv : {};
+
+/**
+ * @deprecated Instructions will be provided on https://pluv.io on how to host this yourself instead.
+ * @date April 27, 2025
+ */
+export const createPluvHandler = <
+    TPluvServer extends PluvServer<CloudflarePlatform<any, any>, any, any, any>,
+>(
+    config: CreatePluvHandlerConfig<TPluvServer, Id<InferCloudflarePluvHandlerEnv<TPluvServer>>>,
+): CreatePluvHandlerResult<Id<InferCloudflarePluvHandlerEnv<TPluvServer>>> => {
+    const { authorize, binding, endpoint = "/api/pluv", modify, io } = config;
+
+    const DurableObject = class extends BaseDurableObject<
+        Id<InferCloudflarePluvHandlerEnv<TPluvServer>>
+    > {
+        private _room: IORoom<CloudflarePlatform<any, any>>;
+
+        constructor(
+            state: DurableObjectState,
+            env: Id<InferCloudflarePluvHandlerEnv<TPluvServer>>,
+        ) {
+            super(state, env);
+
+            this._room = io.createRoom(state.id.toString(), { env, state });
+        }
+
+        public async webSocketClose(
+            ws: WebSocket,
+            code: number,
+            reason: string,
+            wasClean: boolean,
+        ): Promise<void> {
+            if (io._defs.platform._config.registrationMode !== "detached") return;
+
+            const onCloseHandler = this._room.onClose(ws);
+
+            await onCloseHandler({ code, reason });
+        }
+
+        public async webSocketError(ws: WebSocket, error: unknown): Promise<void> {
+            if (io._defs.platform._config.registrationMode !== "detached") return;
+
+            const onErrorHandler = this._room.onError(ws);
+            const eventError = error instanceof Error ? error : new Error("Internal Error");
+
+            await onErrorHandler({ error: eventError, message: eventError.message });
+        }
+
+        public async webSocketMessage(ws: WebSocket, message: string | ArrayBuffer): Promise<void> {
+            if (io._defs.platform._config.registrationMode !== "detached") return;
+
+            const onMessageHandler = this._room.onMessage(ws);
+
+            await onMessageHandler({ data: message });
+        }
+
+        async fetch(request: Request<any, CfProperties<any>>): Promise<Response> {
+            const isWSRequest = request.headers.get("Upgrade") === "websocket";
+
+            if (!isWSRequest) return new Response("Expected websocket", { status: 400 });
+
+            const { 0: client, 1: server } = new WebSocketPair();
+            const token = new URL(request.url).searchParams.get("token");
+
+            const alarm = await this.ctx.storage.getAlarm();
+            if (alarm !== null)
+                await this.ctx.storage.setAlarm(Date.now() + GARBAGE_COLLECT_INTERVAL_MS);
+
+            await this._room.register(server, { env: this.env, request, token });
+
+            return new Response(null, { status: 101, webSocket: client });
+        }
+
+        public async alarm(alarmInfo?: AlarmInvocationInfo): Promise<void> {
+            await this._room.garbageCollect();
+            await this.ctx.storage.setAlarm(Date.now() + GARBAGE_COLLECT_INTERVAL_MS);
+        }
+    };
+
+    const getDurableObjectNamespace = (
+        env: Id<InferCloudflarePluvHandlerEnv<TPluvServer>>,
+    ): DurableObjectNamespace => {
+        const namespace = env[binding as keyof typeof env] as DurableObjectNamespace;
+
+        if (!namespace) {
+            throw new Error(`Could not find DurableObject binding: ${binding}`);
+        }
+
+        return namespace;
+    };
+
+    const authHandler: PluvHandlerFetch<Id<InferCloudflarePluvHandlerEnv<TPluvServer>>> = async (
+        request,
+        env,
+    ) => {
+        if (!authorize) return null;
+
+        const { pathname, searchParams } = new URL(request.url);
+        const matcher = match<{}>(`${endpoint}/authorize`);
+        const matched = matcher(pathname);
+
+        if (!matched) return null;
+
+        const room = searchParams.get("room");
+
+        if (!room) {
+            return new Response("Not found", {
+                headers: { "Content-Type": "text/plain" },
+                status: 404,
+            });
+        }
+
+        try {
+            const user = await authorize({
+                env,
+                request,
+                room,
+            } as AuthorizeFunctionContext<TPluvServer>);
+
+            if (!user) throw new Error();
+
+            const namespace = getDurableObjectNamespace(env);
+            const durableObjectId = namespace.idFromName(room);
+
+            const token = await io.createToken({
+                env,
+                room: durableObjectId.toString(),
+                user: user as any,
+                request,
+            });
+
+            return new Response(token, {
+                headers: { "Content-Type": "text/plain" },
+                status: 200,
+            });
+        } catch (err) {
+            return new Response(err instanceof Error ? err.message : "Unauthorized", {
+                headers: { "Content-Type": "text/plain" },
+                status: 403,
+            });
+        }
+    };
+
+    const roomHandler: PluvHandlerFetch<Id<InferCloudflarePluvHandlerEnv<TPluvServer>>> = async (
+        request,
+        env,
+    ) => {
+        const { pathname } = new URL(request.url);
+        const matcher = match<{ roomId: string }>(`${endpoint}/room/:roomId`);
+        const matched = matcher(pathname);
+
+        if (!matched) return null;
+
+        const { roomId } = matched.params;
+
+        if (!roomId) {
+            return new Response("Not found", {
+                headers: { "Content-Type": "text/plain" },
+                status: 404,
+            });
+        }
+
+        const namespace = getDurableObjectNamespace(env);
+        const durableObjectId = namespace.idFromName(roomId);
+        const room = namespace.get(durableObjectId);
+
+        return room.fetch(request);
+    };
+
+    const handlerFetch: PluvHandlerFetch<Id<InferCloudflarePluvHandlerEnv<TPluvServer>>> = async (
+        request,
+        env,
+    ) => {
+        return [authHandler, roomHandler].reduce(async (promise, current) => {
+            return await promise.then(async (value) => value ?? (await current(request, env)));
+        }, Promise.resolve<Response | null>(null));
+    };
+
+    const handler: ExportedHandler<Id<InferCloudflarePluvHandlerEnv<TPluvServer>>> = {
+        fetch: async (request, env) => {
+            const response =
+                (await handlerFetch(request, env)) ??
+                new Response("Not Found", {
+                    headers: { "Content-Type": "text/plain" },
+                    status: 404,
+                });
+
+            return modify?.(request, response, env) ?? response;
+        },
+    };
+
+    return { fetch: handlerFetch, DurableObject, handler };
+};

package/src/index.ts

@@ -0,0 +1,13 @@
+export type { CloudflarePlatform, CloudflarePlatformConfig } from "./CloudflarePlatform";
+export { createPluvHandler } from "./createPluvHandler";
+export type {
+    AuthorizeFunction,
+    AuthorizeFunctionContext,
+    CreatePluvHandlerConfig,
+    CreatePluvHandlerResult,
+    PluvHandlerFetch,
+} from "./createPluvHandler";
+export { infer } from "./infer";
+export type { InferCallback } from "./infer";
+export { platformCloudflare } from "./platformCloudflare";
+export type { PlatformCloudflareCreateIOParams } from "./platformCloudflare";

package/src/infer.ts

@@ -0,0 +1,17 @@
+import type { Json } from "@pluv/types";
+import type { identity } from "./utils";
+
+export type InferCallback<
+    TEnv extends Record<string, any> = {},
+    TMeta extends Record<string, Json> = {},
+> = (i: typeof identity) => {
+    env?: (io: TEnv) => TEnv;
+    meta?: (io: TMeta) => TMeta;
+};
+
+export const infer = <
+    TEnv extends Record<string, any> = {},
+    TMeta extends Record<string, Json> = {},
+>(
+    callback: InferCallback<TEnv, TMeta>,
+) => callback;

package/src/platformCloudflare.ts

@@ -0,0 +1,57 @@
+import type { CreateIOParams, InferInitContextType, PluvContext, PluvIOAuthorize } from "@pluv/io";
+import type { BaseUser, Id, IOAuthorize, Json } from "@pluv/types";
+import type { CloudflarePlatformConfig } from "./CloudflarePlatform";
+import { CloudflarePlatform } from "./CloudflarePlatform";
+import type { InferCallback } from "./infer";
+
+export type PlatformCloudflareCreateIOParams<
+    TEnv extends Record<string, any> = {},
+    TMeta extends Record<string, Json> = {},
+    TContext extends Record<string, any> = {},
+    TUser extends BaseUser | null = null,
+> = Id<
+    CloudflarePlatformConfig<TEnv, TMeta> &
+        Omit<
+            CreateIOParams<
+                CloudflarePlatform<IOAuthorize<TUser, TContext>, TEnv, TMeta>,
+                TContext,
+                TUser
+            >,
+            "authorize" | "context" | "platform"
+        > & {
+            authorize?: PluvIOAuthorize<
+                CloudflarePlatform<IOAuthorize<TUser, TContext>, TEnv, TMeta>,
+                TUser,
+                InferInitContextType<CloudflarePlatform<IOAuthorize<TUser, TContext>, TEnv, TMeta>>
+            >;
+            context?: PluvContext<
+                CloudflarePlatform<IOAuthorize<TUser, any>, TEnv, TMeta>,
+                TContext
+            >;
+            types?: InferCallback<TEnv, TMeta>;
+        }
+>;
+
+export const platformCloudflare = <
+    TEnv extends Record<string, any> = {},
+    TMeta extends Record<string, Json> = {},
+    TContext extends Record<string, any> = {},
+    TUser extends BaseUser | null = null,
+>(
+    config: PlatformCloudflareCreateIOParams<TEnv, TMeta, TContext, TUser> = {},
+): CreateIOParams<
+    CloudflarePlatform<IOAuthorize<TUser, TContext>, TEnv, TMeta>,
+    TContext,
+    TUser
+> => {
+    const { authorize, context, crdt, debug, limits } = config;
+
+    return {
+        authorize,
+        context,
+        crdt,
+        debug,
+        limits,
+        platform: () => new CloudflarePlatform<IOAuthorize<TUser, TContext>, TEnv, TMeta>(config),
+    };
+};

package/src/utils/identity.ts

@@ -0,0 +1 @@
+export const identity = <T extends unknown>(x: T): T => x;

package/src/utils/index.ts

@@ -0,0 +1 @@
+export { identity } from "./identity";