@pluv/io 0.0.0

package/src/PluvIO.ts

@@ -0,0 +1,322 @@
+import type {
+    EventRecord,
+    InferIOAuthorize,
+    InferIOAuthorizeUser,
+    InferIOInput,
+    InferIOOutput,
+    IOAuthorize,
+    IOLike,
+    JsonObject,
+    Spread,
+    BaseIOAuthorize,
+} from "@pluv/types";
+import chalk from "chalk";
+import type { AbstractPlatform } from "./AbstractPlatform";
+import type { JWTEncodeParams } from "./authorize";
+import { authorize } from "./authorize";
+import { IORoom } from "./IORoom";
+import type { EventConfig, InferEventConfig } from "./types";
+
+export type InferIOContext<TIO extends PluvIO<any, any, any, any, any>> =
+    TIO extends PluvIO<any, any, infer IContext, any, any> ? IContext : never;
+
+export type InferIOPlatform<TIO extends PluvIO<any, any, any, any>> =
+    TIO extends PluvIO<infer IPlatform, any, any, any, any> ? IPlatform : never;
+
+export type InferIORoom<TIO extends PluvIO<any, any, any, any>> =
+    TIO extends PluvIO<
+        infer IPlatform,
+        infer IAuthorize,
+        infer IContext,
+        infer IInput,
+        infer IOutput
+    >
+        ? IORoom<IPlatform, IAuthorize, IContext, IInput, IOutput>
+        : never;
+
+export interface PluvIORegisterOptions {
+    token?: string;
+}
+
+export interface PluvIOConfig<
+    TPlatform extends AbstractPlatform<any> = AbstractPlatform<any>,
+    TAuthorize extends IOAuthorize<any, any> | null = null,
+    TContext extends JsonObject = {},
+    TInput extends EventRecord<string, any> = {},
+    TOutput extends EventRecord<string, any> = {}
+> {
+    authorize?: TAuthorize;
+    context?: TContext;
+    debug?: boolean;
+    events?: InferEventConfig<TContext, TInput, TOutput>;
+    platform: TPlatform;
+    room?: string;
+}
+
+export class PluvIO<
+    TPlatform extends AbstractPlatform<any> = AbstractPlatform<any>,
+    TAuthorize extends IOAuthorize<any, any> = BaseIOAuthorize,
+    TContext extends JsonObject = {},
+    TInput extends EventRecord<string, any> = {},
+    TOutput extends EventRecord<string, any> = {}
+> implements IOLike<TAuthorize, TInput, TOutput>
+{
+    readonly _authorize: TAuthorize | null = null;
+    readonly _debug: boolean;
+    readonly _events: InferEventConfig<TContext, TInput, TOutput> = {
+        $PING: {
+            resolver: (data, { session }) => {
+                if (!session) return {};
+
+                const currentTime = new Date().getTime();
+
+                session.timers.ping = currentTime;
+
+                return { $PONG: {} };
+            },
+            options: { type: "self" },
+        },
+        $GET_OTHERS: {
+            resolver: (data, { session, sessions }) => {
+                const others = Array.from(sessions.entries())
+                    .filter(([, wsSession]) => wsSession.id !== session?.id)
+                    .reduce<{
+                        [connectionId: string]: {
+                            connectionId: string;
+                            room: string | null;
+                            user: InferIOAuthorizeUser<TAuthorize>;
+                        };
+                    }>(
+                        (acc, [connectionId, { presence, user }]) => ({
+                            ...acc,
+                            [connectionId]: {
+                                connectionId,
+                                presence,
+                                room: this.room,
+                                user: user as InferIOAuthorizeUser<TAuthorize>,
+                            },
+                        }),
+                        {}
+                    );
+
+                return { $OTHERS_RECEIVED: { others } };
+            },
+            options: { type: "sync" },
+        },
+        $UPDATE_PRESENCE: {
+            resolver: ({ presence }, { session }) => {
+                if (!session) return {};
+
+                session.presence = Object.assign(
+                    Object.create(null),
+                    session.presence,
+                    presence
+                );
+
+                return { $PRESENCE_UPDATED: { presence } };
+            },
+        },
+        $UPDATE_STORAGE: {
+            resolver: ({ origin, update }, { doc, room }) => {
+                if (
+                    origin === "$STORAGE_RECEIVED" &&
+                    Object.keys(doc.toJSON()).length
+                ) {
+                    return;
+                }
+
+                const updated = doc.applyUpdate(update);
+                const state = updated.encodeStateAsUpdate();
+
+                this._platform.persistance.setStorageState(room, state);
+
+                return { $STORAGE_UPDATED: { state } };
+            },
+        },
+    } as InferEventConfig<TContext, TInput, TOutput>;
+    readonly _platform: TPlatform;
+
+    readonly room: string | null = null;
+
+    private _context: TContext = {} as TContext;
+    private _rooms = new Map<
+        string,
+        IORoom<TPlatform, TAuthorize, TContext, TInput, TOutput>
+    >();
+
+    constructor(
+        options: PluvIOConfig<TPlatform, TAuthorize, TContext, TInput, TOutput>
+    ) {
+        const {
+            authorize,
+            context,
+            debug = false,
+            events,
+            platform,
+            room,
+        } = options;
+
+        this._debug = debug;
+        this._platform = platform;
+
+        if (authorize) this._authorize = authorize;
+        if (context) this._context = context;
+        if (events) this._events = events;
+        if (room) this.room = room;
+    }
+
+    public async createToken(
+        params: JWTEncodeParams<InferIOAuthorizeUser<InferIOAuthorize<this>>>
+    ): Promise<string> {
+        if (!this._authorize) {
+            throw new Error(
+                "IO does not specify authorize during initialization."
+            );
+        }
+
+        return await authorize({
+            platform: this._platform,
+            secret: this._authorize.secret,
+        }).encode(params);
+    }
+
+    public event<
+        TEvent extends string,
+        TData extends JsonObject = {},
+        TResult extends EventRecord<string, any> = {}
+    >(
+        event: TEvent,
+        config: EventConfig<TContext, TData, TResult>
+    ): PluvIO<
+        TPlatform,
+        TAuthorize,
+        TContext,
+        Spread<[TInput, EventRecord<TEvent, TData>]>,
+        Spread<[TOutput, TResult]>
+    > {
+        if (event.startsWith("$")) {
+            throw new Error('Event name must not start with "$".');
+        }
+
+        const newEvent = {
+            [event]: config,
+        } as InferEventConfig<
+            TContext,
+            EventRecord<TEvent, TData>,
+            TResult extends EventRecord<string, any> ? TResult : {}
+        >;
+
+        /**
+         * !HACK
+         * @description Typing this is becoming way too unmanagable, due to resolver
+         * being able to return void and needing to handle the conditional typing.
+         * Assume the types will work out, and cast as any here.
+         *
+         * TODO
+         * @description Revisit EventResolver and related types to resolve types
+         * without casting to any.
+         *
+         * @author leedavidcs
+         * @date September 25, 2022
+         */
+        return PluvIO.merge(
+            this as any,
+            new PluvIO({
+                events: newEvent as any,
+                platform: this._platform,
+            })
+        ) as any;
+    }
+
+    public getRoom(
+        room: string
+    ): IORoom<TPlatform, TAuthorize, TContext, TInput, TOutput> {
+        if (this.room) {
+            throw new Error("IO cannot getRoom from within a room.");
+        }
+
+        if (!/^[a-z0-9]+[a-z0-9\-_]+[a-z0-9]+$/i.test(room)) {
+            throw new Error("Unsupported room name");
+        }
+
+        const platform = this._platform;
+        const oldRoom = this._rooms.get(room);
+
+        if (oldRoom) return oldRoom;
+
+        const newRoom = new IORoom<
+            TPlatform,
+            TAuthorize,
+            TContext,
+            TInput,
+            TOutput
+        >(room, {
+            authorize: this._authorize ?? undefined,
+            context: this._context,
+            debug: this._debug,
+            events: this._events,
+            onDestroy: () => {
+                this._logDebug(`${chalk.blue("Deleting empty room:")} ${room}`);
+
+                this._rooms.delete(room);
+
+                if (this._debug) {
+                    const rooms = Array.from(this._rooms.keys());
+
+                    this._logDebug(`${chalk.blue("Deleted room:")} ${room}`);
+                    this._logDebug(
+                        `${chalk.blue("Rooms available:")} ${rooms.join(", ")}`
+                    );
+                }
+            },
+            platform,
+        });
+
+        this._rooms.set(room, newRoom);
+
+        if (this._debug) {
+            const rooms = Array.from(this._rooms.keys());
+
+            this._logDebug(`${chalk.blue("Created room:")} ${room}`);
+            this._logDebug(
+                `${chalk.blue("Rooms available:")} ${rooms.join(", ")}`
+            );
+        }
+
+        return newRoom;
+    }
+
+    public static merge<TIO1 extends PluvIO, TIO2 extends PluvIO>(
+        first: TIO1,
+        second: TIO2
+    ): PluvIO<
+        InferIOPlatform<TIO1>,
+        InferIOAuthorize<TIO1>,
+        InferIOContext<TIO1>,
+        Spread<[InferIOInput<TIO1>, InferIOInput<TIO2>]>,
+        Spread<[InferIOOutput<TIO1>, InferIOOutput<TIO2>]>
+    > {
+        const authorize = (first._authorize ??
+            undefined) as InferIOAuthorize<TIO1>;
+        const debug = first._debug;
+        const platform = first._platform as InferIOPlatform<TIO1>;
+        const room = first.room ?? undefined;
+
+        const events1 = first._events;
+        const events2 = second._events;
+
+        const events = Object.assign(Object.create(null), events1, events2);
+
+        return new PluvIO({
+            authorize,
+            debug,
+            events,
+            platform,
+            room,
+        });
+    }
+
+    private _logDebug(...data: any[]): void {
+        this._debug && console.log(...data);
+    }
+}

package/src/PubSub.ts

@@ -0,0 +1,79 @@
+import type { Subject } from "wonka";
+import { makeSubject, subscribe } from "wonka";
+import type { IOPubSubEventMessage } from "./AbstractPubSub";
+import { AbstractPubSub } from "./AbstractPubSub";
+
+export class PubSub extends AbstractPubSub {
+    private _currentSubscriptionId: number = 0;
+    // Map of roomName to subjects
+    private _subjects = new Map<string, Subject<IOPubSubEventMessage<any>>>();
+    // Map of roomName to subscription ids
+    private _subscriptionsRefs = new Map<string, readonly number[]>();
+    // Map of
+    private _unsubscriptions = new Map<
+        number,
+        [roomName: string, unsubscribe: () => void]
+    >();
+
+    public async publish(
+        roomName: string,
+        payload: IOPubSubEventMessage<any>
+    ): Promise<void> {
+        const subject = this._subjects.get(roomName);
+
+        if (!subject) return;
+
+        Promise.resolve(subject.next(payload));
+    }
+
+    public subscribe(
+        roomName: string,
+        onMessage: (message: IOPubSubEventMessage<any>) => void
+    ): Promise<number> {
+        const id = this._currentSubscriptionId++;
+        const refs = this._subscriptionsRefs.get(roomName) ?? [];
+
+        const subject = makeSubject<IOPubSubEventMessage<any>>();
+
+        this._subjects.set(roomName, subject);
+        this._subscriptionsRefs.set(roomName, [...refs, id]);
+
+        const unsubscribe = subscribe(onMessage)(subject.source).unsubscribe;
+
+        this._unsubscriptions.set(id, [roomName, unsubscribe]);
+
+        return Promise.resolve(id);
+    }
+
+    public unsubscribe(subscriptionId: number): void {
+        const [roomName, unsubscribe] =
+            this._unsubscriptions.get(subscriptionId) ?? [];
+
+        if (!roomName || !unsubscribe) return;
+
+        const refs = this._subscriptionsRefs.get(roomName);
+
+        if (!refs) return;
+
+        if (refs.length === 1) {
+            this._subjects.delete(roomName);
+            this._subscriptionsRefs.delete(roomName);
+            this._unsubscriptions.delete(subscriptionId);
+
+            return;
+        }
+
+        const index = refs.indexOf(subscriptionId);
+
+        this._subscriptionsRefs.set(
+            roomName,
+            index === -1
+                ? refs
+                : [...refs.slice(0, index), ...refs.slice(index + 1)]
+        );
+
+        unsubscribe();
+
+        this._unsubscriptions.delete(subscriptionId);
+    }
+}

package/src/authorize.ts

@@ -0,0 +1,81 @@
+import hkdf from "@panva/hkdf";
+import { BaseUser } from "@pluv/types";
+import { EncryptJWT, jwtDecrypt } from "jose";
+import { AbstractPlatform } from "./AbstractPlatform";
+
+const DEFAULT_MAX_AGE_MS = 60_000;
+
+export const getEncryptionKey = async (secret: string): Promise<Uint8Array> => {
+    return await hkdf(
+        "sha256",
+        secret,
+        "",
+        "Pluv.io Generated Encryption Key",
+        32
+    );
+};
+
+export interface JWT<TUser extends BaseUser> {
+    room: string;
+    sub: string;
+    user: TUser;
+}
+
+export interface JWTEncodeParams<TUser extends BaseUser> {
+    maxAge?: number;
+    room: string;
+    user: TUser;
+}
+
+export interface AuthorizeParams {
+    platform: AbstractPlatform;
+    secret: string;
+}
+
+export interface AuthorizeModule {
+    decode: <TUser extends BaseUser>(jwt: string) => Promise<TUser | null>;
+    encode: <TUser extends BaseUser>(
+        params: JWTEncodeParams<TUser>
+    ) => Promise<string>;
+}
+
+const now = () => (Date.now() / 1_000) | 0;
+
+export const authorize = (params: AuthorizeParams) => {
+    const { platform, secret } = params;
+
+    const encode = async <TUser extends BaseUser>(
+        encodeParams: JWTEncodeParams<TUser>
+    ): Promise<string> => {
+        const { maxAge = DEFAULT_MAX_AGE_MS, room, user } = encodeParams;
+
+        const encryptionSecret = await getEncryptionKey(secret);
+
+        const token = await new EncryptJWT({
+            room,
+            sub: room ? `${room}|${user.id}` : user.id,
+            user,
+        })
+            .setProtectedHeader({ alg: "dir", enc: "A256GCM" })
+            .setIssuedAt()
+            .setExpirationTime(now() + maxAge)
+            .setJti(platform.randomUUID())
+            .encrypt(encryptionSecret);
+
+        return token.toString();
+    };
+
+    const decode = async <TUser extends BaseUser>(
+        jwt: string
+    ): Promise<JWT<TUser> | null> => {
+        const encryptionSecret = await getEncryptionKey(secret);
+
+        const { payload } = await jwtDecrypt(jwt, encryptionSecret, {
+            clockTolerance: 15,
+        });
+
+        return (payload as any) ?? null;
+    };
+
+    return { decode, encode };
+};

package/src/createIO.ts

@@ -0,0 +1,51 @@
+import type {
+    BaseClientEventRecord,
+    BaseIOEventRecord,
+    BaseUser,
+    IOAuthorize,
+    JsonObject,
+} from "@pluv/types";
+import type { AbstractPlatform } from "./AbstractPlatform";
+import { PluvIO } from "./PluvIO";
+
+export interface CreateIOParams<
+    TPlatform extends AbstractPlatform<any> = AbstractPlatform<any>,
+    TContext extends JsonObject = {},
+    TAuthorizeUser extends BaseUser = BaseUser,
+    TAuthorizeRequired extends boolean = false
+> {
+    authorize?: IOAuthorize<TAuthorizeUser, TAuthorizeRequired>;
+    context?: TContext;
+    debug?: boolean;
+    platform: TPlatform;
+}
+
+export const createIO = <
+    TPlatform extends AbstractPlatform<any> = AbstractPlatform<any>,
+    TContext extends JsonObject = {},
+    TAuthorizeUser extends BaseUser = BaseUser,
+    TAuthorizeRequired extends boolean = false
+>(
+    params: CreateIOParams<
+        TPlatform,
+        TContext,
+        TAuthorizeUser,
+        TAuthorizeRequired
+    >
+): PluvIO<
+    TPlatform,
+    IOAuthorize<TAuthorizeUser, TAuthorizeRequired>,
+    TContext,
+    BaseClientEventRecord,
+    BaseIOEventRecord<IOAuthorize<TAuthorizeUser, TAuthorizeRequired>>
+> => {
+    const { authorize, context, debug, platform } = params;
+
+    return new PluvIO<
+        TPlatform,
+        IOAuthorize<TAuthorizeUser, TAuthorizeRequired>,
+        TContext,
+        BaseClientEventRecord,
+        BaseIOEventRecord<IOAuthorize<TAuthorizeUser, TAuthorizeRequired>>
+    >({ authorize, context, debug, platform });
+};

package/src/index.ts

@@ -0,0 +1,34 @@
+export type {
+    BaseUser,
+    EventMessage,
+    EventRecord,
+    IOEventMessage,
+} from "@pluv/types";
+export type {
+    ConvertWebSocketConfig,
+    InferWebSocketType,
+} from "./AbstractPlatform";
+export { AbstractPersistance } from "./AbstractPersistance";
+export { AbstractPlatform } from "./AbstractPlatform";
+export type { IOPubSubEventMessage } from "./AbstractPubSub";
+export { AbstractPubSub } from "./AbstractPubSub";
+export type {
+    AbstractCloseEvent,
+    AbstractErrorEvent,
+    AbstractEvent,
+    AbstractMessageEvent,
+    AbstractEventMap,
+    AbstractListener,
+    AbstractWebSocketConfig,
+    AbstractWebSocketHandleErrorParams,
+} from "./AbstractWebSocket";
+export { AbstractWebSocket } from "./AbstractWebSocket";
+export type {
+    AuthorizeModule,
+    AuthorizeParams,
+    JWT,
+    JWTEncodeParams,
+} from "./authorize";
+export { createIO } from "./createIO";
+export type { IORoom } from "./IORoom";
+export type { InferIORoom, PluvIO } from "./PluvIO";

package/src/types.ts

@@ -0,0 +1,93 @@
+import { YjsDoc } from "@pluv/crdt-yjs";
+import type {
+    EventRecord,
+    Id,
+    InputZodLike,
+    JsonObject,
+    MaybePromise,
+} from "@pluv/types";
+import type { AbstractWebSocket } from "./AbstractWebSocket";
+
+export interface Console {
+    debug(...data: any[]): void;
+    error(...data: any[]): void;
+    info(...data: any[]): void;
+    log(...data: any[]): void;
+    warn(...data: any[]): void;
+}
+
+declare global {
+    var console: {
+        log: (...data: any[]) => void;
+    };
+}
+
+export interface EventConfig<
+    TContext extends JsonObject = {},
+    TData extends JsonObject = {},
+    TResult extends EventRecord<string, any> = {}
+> {
+    input?: InputZodLike<TData>;
+    options?: SendMessageOptions;
+    resolver: EventResolver<TContext, TData, TResult>;
+}
+
+export type EventConfigType = "broadcast" | "self" | "sync";
+
+export type EventResolver<
+    TContext extends JsonObject = {},
+    TData extends JsonObject = {},
+    TResult extends EventRecord<string, any> = {}
+> = (
+    data: TData,
+    context: EventResolverContext<TContext>
+) => MaybePromise<TResult | void>;
+
+export interface EventResolverContext<TContext extends JsonObject = {}> {
+    context: TContext;
+    doc: YjsDoc<any>;
+    room: string;
+    /**
+     * !HACK
+     * @description Session should only not exist when invoking the event as a
+     * "sync" event on another machine where the session doesn't exist. There must
+     * be a better way to handle this, but going to make this nullable for ease
+     * for now.
+     *
+     * `session` should not be referenced most of the time anyhow (outside of
+     * internal to this library).
+     * @author leedavidcs
+     * @date December 25, 2022
+     */
+    session: WebSocketSession | null;
+    sessions: Map<string, WebSocketSession>;
+}
+
+export type InferEventConfig<
+    TContext extends JsonObject = {},
+    TInput extends EventRecord<string, any> = {},
+    TOutput extends EventRecord<string, any> = {}
+> = {
+    [P in keyof TInput]: P extends string
+        ? Id<EventConfig<TContext, TInput[P], TOutput>>
+        : never;
+};
+
+export type SendMessageOptions =
+    | { type?: "broadcast"; sessionIds?: readonly string[] }
+    | { type: "self" }
+    | { type: "sync" };
+
+export interface WebSocketSessionTimers {
+    ping: number;
+}
+
+export interface WebSocketSession {
+    id: string;
+    presence: JsonObject | null;
+    quit: boolean;
+    room: string;
+    timers: WebSocketSessionTimers;
+    webSocket: AbstractWebSocket;
+    user: JsonObject | null;
+}

package/tsconfig.json

@@ -0,0 +1,5 @@
+{
+	"extends": "@pluv/tsconfig/library.json",
+	"include": ["next-env.d.ts", "**/*.ts", "**/*.tsx"],
+	"exclude": ["node_modules"]
+}