flarecord 0.0.1

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "flarecord",
+  "version": "0.0.1",
+  "description": "discord gateway client for cloudflare workers. built with typescript and optimized for durable objects.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vaishnav-mk/flarecord.git"
+  },
+  "keywords": [
+    "discord",
+    "discord-bot",
+    "discord-gateway",
+    "cloudflare",
+    "cloudflare-workers",
+    "durable-objects",
+    "websocket",
+    "typescript"
+  ],
+  "author": "vaishnav-mk",
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20241106.0",
+    "typescript": "^5.5.2"
+  },
+  "dependencies": {
+    "discord-api-types": "^0.38.37",
+    "discord.js": "^14.25.1"
+  }
+}

package/src/core/bot-base.ts

@@ -0,0 +1,90 @@
+import { DiscordGateway } from "./gateway";
+import type { DurableObjectState } from "@cloudflare/workers-types";
+import type { ReadyData, MessageData } from "../types";
+
+export interface DiscordClientOptions {
+  token: string;
+  intents: number;
+  storageKey?: string;
+  onReady?: (data: ReadyData) => void;
+  onMessage?: (data: MessageData) => void;
+  onError?: (error: Error) => void;
+  onDispatch?: (event: string, data: unknown) => void;
+}
+
+export class DiscordClient {
+  private ctx: DurableObjectState;
+  private gateway: DiscordGateway | null = null;
+  private initialized = false;
+  private options: DiscordClientOptions;
+
+  constructor(ctx: DurableObjectState, options: DiscordClientOptions) {
+    this.ctx = ctx;
+    this.options = options;
+  }
+
+  getGateway(): DiscordGateway | null {
+    return this.gateway;
+  }
+
+  isConnected(): boolean {
+    return this.gateway?.isConnected ?? false;
+  }
+
+  getToken(): string {
+    return this.options.token;
+  }
+
+  async fetch(_request: Request): Promise<Response> {
+    if (!this.initialized) {
+      await new Promise(resolve => setTimeout(resolve, 100));
+      await this.initialize();
+      this.initialized = true;
+    }
+    return new Response("Bot is running!", {
+      headers: { "Content-Type": "text/plain" },
+    });
+  }
+
+  async alarm(): Promise<void> {
+    if (this.gateway?.isConnected) {
+      await this.gateway.sendHeartbeat();
+    }
+  }
+
+  private async initialize(): Promise<void> {
+    await new Promise(resolve => setTimeout(resolve, 200));
+
+    this.gateway = new DiscordGateway(
+      this.options.token,
+      this.options.intents,
+      this.ctx,
+      {
+        storageKey: this.options.storageKey || "gatewayState",
+        onDispatch: (event, data) => {
+          this.options.onDispatch?.(event, data);
+        },
+      }
+    );
+
+    this.gateway.onReady((data) => {
+      this.options.onReady?.(data);
+    });
+
+    this.gateway.onMessage((data) => {
+      this.options.onMessage?.(data);
+    });
+
+    this.gateway.onError((error) => {
+      this.options.onError?.(error);
+    });
+
+    try {
+      await this.gateway.connect();
+    } catch (error) {
+      this.options.onError?.(
+        error instanceof Error ? error : new Error("Failed to connect")
+      );
+    }
+  }
+}

package/src/core/client.ts

@@ -0,0 +1,90 @@
+import { DiscordGateway } from "./gateway";
+import type { DurableObjectState } from "@cloudflare/workers-types";
+import type { ReadyData, MessageData } from "../types";
+
+export interface DiscordClientOptions {
+  token: string;
+  intents: number;
+  storageKey?: string;
+  onReady?: (data: ReadyData) => void;
+  onMessage?: (data: MessageData) => void;
+  onError?: (error: Error) => void;
+  onDispatch?: (event: string, data: unknown) => void;
+}
+
+export class DiscordClient {
+  private ctx: DurableObjectState;
+  private gateway: DiscordGateway | null = null;
+  private initialized = false;
+  private options: DiscordClientOptions;
+
+  constructor(ctx: DurableObjectState, options: DiscordClientOptions) {
+    this.ctx = ctx;
+    this.options = options;
+  }
+
+  getGateway(): DiscordGateway | null {
+    return this.gateway;
+  }
+
+  isConnected(): boolean {
+    return this.gateway?.isConnected ?? false;
+  }
+
+  getToken(): string {
+    return this.options.token;
+  }
+
+  async fetch(_request: Request): Promise<Response> {
+    if (!this.initialized) {
+      await new Promise(resolve => setTimeout(resolve, 100));
+      await this.initialize();
+      this.initialized = true;
+    }
+    return new Response("Bot is running!", {
+      headers: { "Content-Type": "text/plain" },
+    });
+  }
+
+  async alarm(): Promise<void> {
+    if (this.gateway?.isConnected) {
+      await this.gateway.sendHeartbeat();
+    }
+  }
+
+  private async initialize(): Promise<void> {
+    await new Promise(resolve => setTimeout(resolve, 200));
+
+    this.gateway = new DiscordGateway(
+      this.options.token,
+      this.options.intents,
+      this.ctx,
+      {
+        storageKey: this.options.storageKey || "gatewayState",
+        onDispatch: (event, data) => {
+          this.options.onDispatch?.(event, data);
+        },
+      }
+    );
+
+    this.gateway.onReady((data) => {
+      this.options.onReady?.(data);
+    });
+
+    this.gateway.onMessage((data) => {
+      this.options.onMessage?.(data);
+    });
+
+    this.gateway.onError((error) => {
+      this.options.onError?.(error);
+    });
+
+    try {
+      await this.gateway.connect();
+    } catch (error) {
+      this.options.onError?.(
+        error instanceof Error ? error : new Error("Failed to connect")
+      );
+    }
+  }
+}

package/src/core/connection.ts

@@ -0,0 +1,238 @@
+import { GATEWAY_BASE_URL, WEBSOCKET_READY_STATE_OPEN } from "../types/constants";
+import { GatewayPayload, ReadyData, MessageData } from "../types";
+import { WebSocketManager } from "../utils/websocket";
+import { GatewayHandlers } from "./handlers";
+import { ReconnectManager } from "../utils/reconnect";
+import { SessionManager } from "../utils/session";
+import { HeartbeatManager } from "./heartbeat";
+import { MessageHandler } from "./message-handler";
+import { Logger, LogLevel, createLogger } from "../utils/logger";
+import type { DurableObjectState, WebSocket } from "@cloudflare/workers-types";
+
+export class GatewayConnection {
+  private wsManager: WebSocketManager;
+  private token: string;
+  private ctx: DurableObjectState;
+  private storageKey: string;
+  private sequence: { value: number | null } = { value: null };
+  private handlers: GatewayHandlers;
+  private reconnectManager: ReconnectManager;
+  private sessionManager: SessionManager;
+  private heartbeatManager: HeartbeatManager;
+  private messageHandler: MessageHandler;
+  private onDispatch?: (event: string, data: unknown) => void;
+  private logger: Logger;
+  private isShuttingDown = false;
+
+  private onReadyCallback: ((data: ReadyData) => void) | null = null;
+  private onMessageCallback: ((data: MessageData) => void) | null = null;
+  private onErrorCallback: ((error: Error) => void) | null = null;
+
+  constructor(
+    token: string,
+    intents: number,
+    ctx: DurableObjectState,
+    config: {
+      storageKey: string;
+      identifyProperties: { os: string; browser: string; device: string };
+      maxReconnectAttempts?: number;
+      reconnectDelays?: {
+        initial: number;
+        max: number;
+        backoffMultiplier: number;
+      };
+      onDispatch?: (event: string, data: unknown) => void;
+      logger?: Logger;
+      debug?: boolean;
+    }
+  ) {
+    this.token = token;
+    this.ctx = ctx;
+    this.storageKey = config.storageKey;
+    this.onDispatch = config.onDispatch;
+    this.logger = config.logger || createLogger({
+      level: config.debug ? LogLevel.DEBUG : LogLevel.INFO,
+    });
+
+    this.wsManager = new WebSocketManager();
+    this.reconnectManager = new ReconnectManager(
+      config.maxReconnectAttempts,
+      config.reconnectDelays
+    );
+    this.sessionManager = new SessionManager(
+      token,
+      ctx,
+      this.storageKey,
+      config.identifyProperties,
+      (p: GatewayPayload) => this.wsManager.send(p)
+    );
+    this.heartbeatManager = new HeartbeatManager(
+      ctx,
+      this.storageKey,
+      this.sequence,
+      (p: GatewayPayload) => this.wsManager.send(p)
+    );
+    this.handlers = new GatewayHandlers(
+      ctx,
+      this.storageKey,
+      this.sequence,
+      (data) => this.onReadyCallback?.(data),
+      (data) => this.onMessageCallback?.(data),
+      this.onDispatch,
+      this.logger
+    );
+    this.messageHandler = new MessageHandler(
+      this.handlers,
+      this.sessionManager,
+      this.heartbeatManager,
+      (shouldResume) => this.reconnect(shouldResume),
+      ctx,
+      this.storageKey,
+      intents,
+      this.logger
+    );
+  }
+
+  get ws(): WebSocket | null {
+    return this.wsManager.ws;
+  }
+
+  get isConnected(): boolean {
+    return this.wsManager.ws?.readyState === WEBSOCKET_READY_STATE_OPEN;
+  }
+
+  async connect(): Promise<void> {
+    if (this.isShuttingDown) {
+      this.logger.warn("Connection attempt blocked: shutdown in progress");
+      return;
+    }
+
+    try {
+      this.logger.debug("Fetching gateway URL");
+      const gatewayUrl = await this.getGatewayUrl();
+      this.logger.debug("Connecting to gateway", { url: gatewayUrl });
+      await this.wsManager.connect(gatewayUrl);
+      this.wsManager.setupEventListeners(
+        (data: string | ArrayBuffer | ArrayBufferView) => this.handleMessage(data),
+        async (code: number, reason: string) => await this.handleClose(code, reason),
+        (error: Error) => this.handleWebSocketError(error)
+      );
+      this.reconnectManager.reset();
+      this.logger.info("Gateway connection established");
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error("Connection failed");
+      this.logger.error("Failed to connect to gateway", err);
+      this.onErrorCallback?.(err);
+      if (!this.isShuttingDown) {
+      await this.reconnectManager.scheduleReconnect(() => this.connect());
+      }
+    }
+  }
+
+  private async getGatewayUrl(): Promise<string> {
+    const response = await fetch(GATEWAY_BASE_URL, {
+      headers: { Authorization: `Bot ${this.token}` },
+    });
+
+    if (!response.ok) {
+      throw new Error(`Failed to get Gateway URL: ${response.status}`);
+    }
+
+    const data = (await response.json()) as { url: string };
+    const wsUrl = data.url.replace(/^wss:/, "https:");
+    return `${wsUrl}?v=10&encoding=json`;
+  }
+
+  private async handleMessage(
+    data: string | ArrayBuffer | ArrayBufferView
+  ): Promise<void> {
+    try {
+      const text = this.wsManager.decodeMessage(data);
+      const payload: GatewayPayload = JSON.parse(text);
+      this.logger.debug("Received gateway payload", { op: payload.op, t: payload.t });
+      await this.messageHandler.handle(payload);
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error("Message handling failed");
+      this.logger.error("Error handling gateway message", err);
+      this.onErrorCallback?.(err);
+    }
+  }
+
+  private async handleClose(code: number, reason: string): Promise<void> {
+    this.logger.warn("WebSocket closed", { code, reason });
+    await this.heartbeatManager.cancel();
+    
+    if (this.isShuttingDown) {
+      this.logger.debug("Shutdown in progress, not reconnecting");
+      return;
+    }
+
+    const shouldResume = this.messageHandler.shouldResume(code);
+    this.logger.debug("Determining reconnect strategy", { shouldResume, code });
+    await this.reconnect(shouldResume);
+  }
+
+  private handleWebSocketError(error: Error): void {
+    this.logger.error("WebSocket error", error);
+    this.onErrorCallback?.(error);
+    
+    if (!this.isShuttingDown && !this.isConnected) {
+      this.logger.debug("Scheduling reconnect due to WebSocket error");
+      this.reconnectManager.scheduleReconnect(() => this.connect()).catch((err) => {
+        this.logger.error("Failed to schedule reconnect", err);
+      });
+    }
+  }
+
+  private async reconnect(shouldResume: boolean): Promise<void> {
+    if (this.isShuttingDown) {
+      this.logger.debug("Reconnect blocked: shutdown in progress");
+      return;
+    }
+
+    try {
+    await this.reconnectManager.reconnect(
+      shouldResume,
+      this.ctx,
+      this.storageKey,
+      () => this.connect(),
+        () => {
+          this.logger.debug("Closing WebSocket connection");
+          this.wsManager.close();
+        }
+    );
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error("Reconnect failed");
+      this.logger.error("Reconnection failed", err);
+      this.onErrorCallback?.(err);
+    }
+  }
+
+  async disconnect(): Promise<void> {
+    this.logger.info("Disconnecting from gateway");
+    this.isShuttingDown = true;
+    await this.heartbeatManager.cancel();
+    this.wsManager.close();
+    this.reconnectManager.reset();
+  }
+
+  onReady(callback: (data: ReadyData) => void): void {
+    this.onReadyCallback = callback;
+  }
+
+  onMessage(callback: (data: MessageData) => void): void {
+    this.onMessageCallback = callback;
+  }
+
+  onError(callback: (error: Error) => void): void {
+    this.onErrorCallback = callback;
+  }
+
+  async sendHeartbeat(): Promise<void> {
+    if (!this.isConnected) {
+      await this.heartbeatManager.cancel();
+      return;
+    }
+    await this.heartbeatManager.send();
+  }
+}

package/src/core/gateway.ts

@@ -0,0 +1,78 @@
+import { GatewayConnection } from "./connection";
+import {
+  ReadyData,
+  GatewayConfig,
+  DEFAULT_IDENTIFY_PROPERTIES,
+  MessageData,
+} from "../types";
+import {
+  DEFAULT_RECONNECT_DELAYS,
+  DEFAULT_STORAGE_KEY,
+  DEFAULT_MAX_RECONNECT_ATTEMPTS,
+} from "../types/constants";
+import { createLogger, LogLevel } from "../utils/logger";
+import type { DurableObjectState, WebSocket } from "@cloudflare/workers-types";
+
+export class DiscordGateway {
+  private connection: GatewayConnection;
+
+  constructor(
+    token: string,
+    intents: number,
+    ctx: DurableObjectState,
+    config?: Partial<GatewayConfig>
+  ) {
+    const storageKey = config?.storageKey || DEFAULT_STORAGE_KEY;
+    const identifyProperties =
+      config?.identifyProperties || DEFAULT_IDENTIFY_PROPERTIES;
+    const maxReconnectAttempts =
+      config?.maxReconnectAttempts || DEFAULT_MAX_RECONNECT_ATTEMPTS;
+    const reconnectDelays =
+      config?.reconnectDelays || DEFAULT_RECONNECT_DELAYS;
+    const logger = config?.logger || createLogger({
+      level: config?.debug ? LogLevel.DEBUG : LogLevel.INFO,
+    });
+
+    this.connection = new GatewayConnection(token, intents, ctx, {
+      storageKey,
+      identifyProperties,
+      maxReconnectAttempts,
+      reconnectDelays,
+      onDispatch: config?.onDispatch,
+      logger,
+      debug: config?.debug,
+    });
+  }
+
+  get ws(): WebSocket | null {
+    return this.connection.ws;
+  }
+
+  get isConnected(): boolean {
+    return this.connection.isConnected;
+  }
+
+  async connect(): Promise<void> {
+    await this.connection.connect();
+  }
+
+  async disconnect(): Promise<void> {
+    await this.connection.disconnect();
+  }
+
+  async sendHeartbeat(): Promise<void> {
+    await this.connection.sendHeartbeat();
+  }
+
+  onReady(callback: (data: ReadyData) => void): void {
+    this.connection.onReady(callback);
+  }
+
+  onMessage(callback: (data: MessageData) => void): void {
+    this.connection.onMessage(callback);
+  }
+
+  onError(callback: (error: Error) => void): void {
+    this.connection.onError(callback);
+  }
+}

package/src/core/handlers.ts

@@ -0,0 +1,136 @@
+import { GatewayOpcode, GatewayEvent } from "../types/constants";
+import {
+  GatewayPayload,
+  HelloData,
+  ReadyData,
+  GatewayState,
+  MessageData,
+} from "../types";
+import type { DurableObjectState } from "@cloudflare/workers-types";
+import type { GatewayMessageCreateDispatchData } from "discord-api-types/v10";
+import type { Logger } from "../utils/logger";
+
+export class GatewayHandlers {
+  constructor(
+    private ctx: DurableObjectState,
+    private storageKey: string,
+    private sequence: { value: number | null },
+    private onReady: (data: ReadyData) => void,
+    private onMessage: (data: MessageData) => void,
+    private onDispatch: ((event: string, data: unknown) => void) | undefined,
+    private logger: Logger
+  ) {}
+
+  async handleHello(data: HelloData): Promise<void> {
+    this.logger.debug("Handling HELLO", { heartbeatInterval: data.heartbeat_interval });
+    const state = await this.getState();
+    await this.ctx.storage.put(this.storageKey, {
+      heartbeatInterval: data.heartbeat_interval,
+      sequence: this.sequence.value,
+      sessionId: state?.sessionId ?? null,
+      reconnectAttempts: 0,
+      shouldResume: state?.sessionId !== null && state?.sessionId !== undefined,
+    } satisfies GatewayState);
+  }
+
+  async handleReady(data: ReadyData): Promise<void> {
+    this.logger.info("Bot ready", { userId: data.user.id, username: data.user.username });
+    const state = await this.getState();
+    if (state) {
+      await this.ctx.storage.put(this.storageKey, {
+        ...state,
+        sessionId: data.session_id,
+        shouldResume: true,
+        reconnectAttempts: 0,
+      } satisfies GatewayState);
+    }
+    this.onReady(data);
+  }
+
+  handleResumed(): void {
+    this.logger.info("Session resumed");
+    this.ctx.storage.get(this.storageKey).then((state) => {
+      const gatewayState = this.validateState(state);
+      if (gatewayState) {
+        this.ctx.storage.put(this.storageKey, {
+          ...gatewayState,
+          reconnectAttempts: 0,
+        } satisfies GatewayState);
+      }
+    });
+  }
+
+  handleDispatch(payload: GatewayPayload): void {
+    if (payload.s !== null && payload.s !== undefined) {
+      this.sequence.value = payload.s;
+      this.updateSequenceInStorage();
+    }
+
+    if (!payload.t) {
+      return;
+    }
+
+    const event = payload.t;
+    if (event === GatewayEvent.READY) {
+      this.handleReady(payload.d as ReadyData);
+    } else if (event === GatewayEvent.MESSAGE_CREATE) {
+      this.handleMessageCreate(payload);
+    } else if (event === GatewayEvent.RESUMED) {
+      this.handleResumed();
+    }
+
+    if (this.onDispatch) {
+      this.onDispatch(event, payload.d);
+    }
+  }
+
+  private handleMessageCreate(payload: GatewayPayload): void {
+    const messageData = payload.d as GatewayMessageCreateDispatchData;
+    const opcodeName = this.getOpcodeName(payload.op);
+    
+    const enrichedMessage: MessageData = {
+      ...messageData,
+      _gatewayMetadata: {
+        opcode: payload.op,
+        opcodeName,
+        event: payload.t ?? "UNKNOWN",
+        sequence: payload.s ?? null,
+      },
+    };
+    this.onMessage(enrichedMessage);
+    }
+
+  private getOpcodeName(opcode: number): string {
+    const entry = Object.entries(GatewayOpcode).find(
+      ([, value]) => value === opcode
+    );
+    return entry?.[0] ?? "UNKNOWN";
+  }
+
+  private async getState(): Promise<GatewayState | null> {
+    const state = await this.ctx.storage.get(this.storageKey);
+    return this.validateState(state);
+  }
+
+  private validateState(state: unknown): GatewayState | null {
+    if (state === null || state === undefined) {
+      return null;
+    }
+    if (typeof state === "object" && "heartbeatInterval" in state) {
+      return state as GatewayState;
+    }
+    return null;
+  }
+
+  private updateSequenceInStorage(): void {
+    this.ctx.storage.get(this.storageKey).then((state) => {
+      const gatewayState = this.validateState(state);
+      if (gatewayState) {
+        this.ctx.storage.put(this.storageKey, {
+          ...gatewayState,
+          sequence: this.sequence.value,
+        } satisfies GatewayState);
+      }
+    });
+  }
+}