akanjs 0.0.1 → 2.0.0-beta.0

package/service/predefinedAdaptor/websocket.adaptor.ts

@@ -0,0 +1,313 @@
+import type { BaseEnv, Cls } from "akanjs/base";
+import { adapt } from "../adapt";
+import { RedisCache } from "./cache.adaptor";
+import { ProtobufCompressor } from "./compress.adaptor";
+
+export interface WsSocketData {
+  socketId?: string;
+  createdAt?: number;
+}
+export type WsRedisEventHandler = (roomId: string, data: unknown) => void;
+
+export interface WebsocketAdaptor {
+  /** Publish data to a room across all server instances */
+  publish(roomId: string, data: unknown): void;
+  /** Register an event handler for incoming cross-server messages */
+  setEventHandler(handler: WsRedisEventHandler): void;
+  /** Unregister the event handler */
+  clearEventHandler(): void;
+  /** Register endpoint return type info for protobuf encoding */
+  registerEndpoint(key: string, returnRef: Cls, arrDepth: number): void;
+  /** Register a socket joining a room (tracked in Redis for cross-server awareness) */
+  joinRoom(ws: Bun.ServerWebSocket<unknown>, room: string): Promise<void>;
+  /** Remove a socket from a room */
+  leaveRoom(ws: Bun.ServerWebSocket<unknown>, room: string): Promise<void>;
+  /** Remove a socket from all rooms and clean up its Redis state */
+  leaveAllRooms(ws: Bun.ServerWebSocket<unknown>): Promise<void>;
+  /** Register a socket connection on this server */
+  registerSocket(ws: Bun.ServerWebSocket<unknown>, meta?: Record<string, string>): Promise<void>;
+  /** Unregister a socket connection */
+  unregisterSocket(ws: Bun.ServerWebSocket<unknown>): Promise<void>;
+}
+
+interface BufferedMessage {
+  channel: string;
+  message: Buffer;
+}
+
+const WEBSOCKET_PREFIX = "ws:";
+const BROADCAST_CHANNEL = "ws:broadcast";
+
+export class WebSocketRedisAdaptor
+  extends adapt("wsRedis", ({ plug, env }) => ({
+    redis: plug(RedisCache, (cache) => cache.getClient()),
+    compressor: plug(ProtobufCompressor),
+    serverId: env(
+      ({ appName, environment, operationMode }: BaseEnv) =>
+        `${appName}-${environment}-${operationMode}-${process.env.POD_NAME ?? Bun.randomUUIDv7()}`,
+    ),
+    publisher: plug(RedisCache, (cache) =>
+      cache.getClient().duplicate({ lazyConnect: true, retryStrategy: (times) => Math.min(times * 200, 5000) }),
+    ),
+    subscriber: plug(RedisCache, (cache) =>
+      cache.getClient().duplicate({ lazyConnect: true, retryStrategy: (times) => Math.min(times * 200, 5000) }),
+    ),
+  }))
+  implements WebsocketAdaptor
+{
+  readonly #buffer: BufferedMessage[] = [];
+  readonly #maxBufferSize = 10000;
+  readonly #endpointMap = new Map<string, { returnRef: Cls; arrDepth: number }>();
+  #eventHandler: WsRedisEventHandler | null = null;
+  #publisherReady = false;
+  #heartbeatInterval: Timer | null = null;
+
+  override async onInit() {
+    
+    this.publisher.on("connect", () => {
+      this.#publisherReady = true;
+      this.logger.verbose("Publisher connected");
+      this.#flushBuffer();
+    });
+    this.publisher.on("close", () => {
+      this.#publisherReady = false;
+      this.logger.warn("Publisher disconnected, buffering messages...");
+    });
+    this.publisher.on("error", (err: Error) => {
+      this.logger.warn(`Publisher error: ${err.message}`);
+    });
+
+    this.subscriber.on("error", (err: Error) => {
+      this.logger.warn(`Subscriber error: ${err.message}`);
+    });
+
+    await this.publisher.connect();
+    await this.subscriber.connect();
+
+    await this.subscriber.subscribe(BROADCAST_CHANNEL, (err?: Error | null) => {
+      if (err) this.logger.warn(`Subscribe error: ${err.message}`);
+    });
+
+    this.subscriber.on("messageBuffer", (_channel: string, message: Buffer) => {
+      try {
+        const unpacked = this.#unpackMessage(message);
+        if (!unpacked) throw new Error("Failed to unpack message");
+        if (unpacked.origin === this.serverId || !this.#eventHandler) return;
+        const endpointKey = this.#getEndpointKey(unpacked.roomId);
+        const endpointInfo = endpointKey ? this.#endpointMap.get(endpointKey) : null;
+        if (!endpointInfo) throw new Error(`No endpoint registered for roomId ${unpacked.roomId}`);
+        const decoded = this.compressor.decode(endpointInfo.returnRef, endpointInfo.arrDepth, unpacked.payload, {
+          raw: true,
+        });
+        this.#eventHandler(unpacked.roomId, decoded);
+      } catch (err) {
+        this.logger.warn(`Failed to handle Redis WS message: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    });
+
+    await this.redis.set(`${WEBSOCKET_PREFIX}server:${this.serverId}`, Date.now().toString(), "EX", 60);
+    this.#heartbeatInterval = setInterval(async () => {
+      try {
+        await this.redis.expire(`${WEBSOCKET_PREFIX}server:${this.serverId}:sockets`, 60);
+        await this.redis.set(`${WEBSOCKET_PREFIX}server:${this.serverId}`, Date.now().toString(), "EX", 60);
+      } catch (err) {
+        this.logger.warn(`Heartbeat failed: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    }, 30_000);
+
+    this.logger.verbose(`WebSocket Redis adaptor initialized (serverId: ${this.serverId})`);
+  }
+
+  override async onDestroy() {
+    
+    if (this.#heartbeatInterval) {
+      clearInterval(this.#heartbeatInterval);
+      this.#heartbeatInterval = null;
+    }
+
+    await this.#cleanupServer();
+
+    if (this.subscriber) {
+      try {
+        await this.subscriber.unsubscribe(BROADCAST_CHANNEL);
+      } catch {}
+      this.subscriber.disconnect();
+    }
+    if (this.publisher) {
+      await this.#flushBuffer();
+      this.publisher.disconnect();
+    }
+    this.#eventHandler = null;
+    this.#publisherReady = false;
+    this.logger.verbose("WebSocket Redis adaptor destroyed");
+  }
+
+  publish(roomId: string, data: unknown): void {
+    const endpointKey = this.#getEndpointKey(roomId);
+    const endpointInfo = endpointKey ? this.#endpointMap.get(endpointKey) : null;
+    if (!endpointInfo) {
+      this.logger.warn(`No endpoint registered for roomId ${roomId}, skipping publish`);
+      return;
+    }
+    const payload = this.compressor.encode(endpointInfo.returnRef, endpointInfo.arrDepth, data);
+    if (!payload) {
+      this.logger.warn(`Compressor encode failed for ${endpointKey}, skipping publish`);
+      return;
+    }
+    const message = this.#packMessage(this.serverId, roomId, payload);
+    if (this.#publisherReady && this.publisher) {
+      this.publisher.publish(BROADCAST_CHANNEL, message).catch((err: Error) => {
+        this.logger.warn(`Publish failed, buffering: ${err.message}`);
+        this.#addToBuffer(BROADCAST_CHANNEL, message);
+      });
+    } else this.#addToBuffer(BROADCAST_CHANNEL, message);
+  }
+
+  setEventHandler(handler: WsRedisEventHandler): void {
+    this.#eventHandler = handler;
+  }
+
+  clearEventHandler(): void {
+    this.#eventHandler = null;
+  }
+
+  registerEndpoint(key: string, returnRef: Cls, arrDepth: number): void {
+    this.#endpointMap.set(key, { returnRef, arrDepth });
+  }
+
+  #getEndpointKey(roomId: string): string {
+    const idx = roomId.indexOf("-");
+    return idx >= 0 ? roomId.substring(0, idx) : roomId;
+  }
+
+  async joinRoom(ws: Bun.ServerWebSocket<unknown>, room: string): Promise<void> {
+    const socketId = this.#getSocketId(ws);
+    const pipeline = this.redis.multi();
+    pipeline.sadd(`${WEBSOCKET_PREFIX}room:${room}`, socketId);
+    pipeline.sadd(`${WEBSOCKET_PREFIX}socket:${socketId}:rooms`, room);
+    await pipeline.exec();
+  }
+
+  async leaveRoom(ws: Bun.ServerWebSocket<unknown>, room: string): Promise<void> {
+    const socketId = this.#getSocketId(ws);
+    const pipeline = this.redis.multi();
+    pipeline.srem(`${WEBSOCKET_PREFIX}room:${room}`, socketId);
+    pipeline.srem(`${WEBSOCKET_PREFIX}socket:${socketId}:rooms`, room);
+    await pipeline.exec();
+  }
+
+  async leaveAllRooms(ws: Bun.ServerWebSocket<unknown>): Promise<void> {
+    const socketId = this.#getSocketId(ws);
+    const rooms = await this.redis.smembers(`${WEBSOCKET_PREFIX}socket:${socketId}:rooms`);
+    const pipeline = this.redis.multi();
+    for (const room of rooms) {
+      pipeline.srem(`${WEBSOCKET_PREFIX}room:${room}`, socketId);
+    }
+    pipeline.del(`${WEBSOCKET_PREFIX}socket:${socketId}:rooms`);
+    pipeline.del(`${WEBSOCKET_PREFIX}socket:${socketId}`);
+    pipeline.srem(`${WEBSOCKET_PREFIX}server:${this.serverId}:sockets`, socketId);
+    await pipeline.exec();
+  }
+
+  #getSocketId(ws: Bun.ServerWebSocket<unknown>): string {
+    const data = ws.data as WsSocketData;
+    if (!data.socketId) data.socketId = `${this.serverId}-${Bun.randomUUIDv7()}`;
+    return data.socketId;
+  }
+
+  async registerSocket(ws: Bun.ServerWebSocket<unknown>, meta: Record<string, string> = {}): Promise<void> {
+    const pipeline = this.redis.multi();
+    const socketId = this.#getSocketId(ws);
+    pipeline.hset(`${WEBSOCKET_PREFIX}socket:${socketId}`, {
+      serverId: this.serverId,
+      connectedAt: Date.now().toString(),
+      ...meta,
+    });
+    pipeline.sadd(`${WEBSOCKET_PREFIX}server:${this.serverId}:sockets`, socketId);
+    await pipeline.exec();
+  }
+
+  async unregisterSocket(ws: Bun.ServerWebSocket<unknown>): Promise<void> {
+    await this.leaveAllRooms(ws);
+  }
+
+  #packMessage(origin: string, roomId: string, payload: Buffer): Buffer {
+    const originBuf = Buffer.from(origin, "utf-8");
+    const roomIdBuf = Buffer.from(roomId, "utf-8");
+    const message = Buffer.alloc(2 + originBuf.length + 2 + roomIdBuf.length + payload.length);
+    let offset = 0;
+    message.writeUInt16BE(originBuf.length, offset);
+    offset += 2;
+    originBuf.copy(message, offset);
+    offset += originBuf.length;
+    message.writeUInt16BE(roomIdBuf.length, offset);
+    offset += 2;
+    roomIdBuf.copy(message, offset);
+    offset += roomIdBuf.length;
+    payload.copy(message, offset);
+    return message;
+  }
+
+  #unpackMessage(buffer: Buffer): { origin: string; roomId: string; payload: Buffer } | null {
+    if (buffer.length < 4) return null;
+    let offset = 0;
+    const originLen = buffer.readUInt16BE(offset);
+    offset += 2;
+    if (buffer.length < offset + originLen + 2) return null;
+    const origin = buffer.subarray(offset, offset + originLen).toString("utf-8");
+    offset += originLen;
+    const roomIdLen = buffer.readUInt16BE(offset);
+    offset += 2;
+    if (buffer.length < offset + roomIdLen) return null;
+    const roomId = buffer.subarray(offset, offset + roomIdLen).toString("utf-8");
+    offset += roomIdLen;
+    const payload = buffer.subarray(offset);
+    return { origin, roomId, payload };
+  }
+
+  #addToBuffer(channel: string, message: Buffer): void {
+    if (this.#buffer.length >= this.#maxBufferSize) {
+      this.#buffer.shift();
+      this.logger.warn("Buffer full, dropping oldest message");
+    }
+    this.#buffer.push({ channel, message });
+  }
+
+  async #flushBuffer(): Promise<void> {
+    if (!this.#publisherReady || !this.publisher || this.#buffer.length === 0) return;
+
+    this.logger.verbose(`Flushing ${this.#buffer.length} buffered messages`);
+    const messages = this.#buffer.splice(0);
+    for (const { channel, message } of messages) {
+      try {
+        await this.publisher.publish(channel, message);
+      } catch {
+        this.#buffer.unshift({ channel, message });
+        this.logger.warn(`Flush failed, ${this.#buffer.length} messages remain buffered`);
+        break;
+      }
+    }
+  }
+
+  async #cleanupServer(): Promise<void> {
+    try {
+      const sockets = await this.redis.smembers(`${WEBSOCKET_PREFIX}server:${this.serverId}:sockets`);
+      const pipeline = this.redis.multi();
+      for (const socketId of sockets) {
+        
+        const rooms = await this.redis.smembers(`${WEBSOCKET_PREFIX}socket:${socketId}:rooms`);
+        for (const room of rooms) {
+          pipeline.srem(`${WEBSOCKET_PREFIX}room:${room}`, socketId);
+        }
+        pipeline.del(`${WEBSOCKET_PREFIX}socket:${socketId}:rooms`);
+        pipeline.del(`${WEBSOCKET_PREFIX}socket:${socketId}`);
+      }
+      pipeline.del(`${WEBSOCKET_PREFIX}server:${this.serverId}:sockets`);
+      pipeline.del(`${WEBSOCKET_PREFIX}server:${this.serverId}`);
+      await pipeline.exec();
+      this.logger.verbose(`Cleaned up ${sockets.length} sockets from Redis`);
+    } catch (err) {
+      this.logger.warn(`Server cleanup failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+}

package/service/serve.ts

@@ -0,0 +1,223 @@
+import { type Cls, INJECT_META } from "akanjs/base";
+import { applyMixins, capitalize, Logger, lowerlize } from "akanjs/common";
+import type { DatabaseModel, FilterInstance } from "akanjs/document";
+
+import {
+  type ExtractInjectInfoObject,
+  type InjectBuilder,
+  InjectInfo,
+  type InjectType,
+  injectionBuilder,
+} from "./injectInfo";
+import type { DatabaseService } from "./types";
+
+interface ServiceOptions {
+  enabled?: boolean;
+  serverMode?: "batch" | "federation";
+}
+export type ServiceType = "database" | "plain";
+
+const avoidKeys = new Set([
+  "onInit",
+  "onDestroy",
+  "_libsOnInit",
+  "_libsOnDestroy",
+  "_preCreate",
+  "_postCreate",
+  "_preUpdate",
+  "_postUpdate",
+  "_preRemove",
+  "_postRemove",
+  "_libsPreCreate",
+  "_libsPostCreate",
+  "_libsPreUpdate",
+  "_libsPostUpdate",
+  "_libsPreRemove",
+  "_libsPostRemove",
+]);
+
+export interface Service {
+  readonly logger: Logger;
+  
+  onInit(): Promise<void>;
+  _libsOnInit(): Promise<void>;
+  onDestroy(): Promise<void>;
+  _libsOnDestroy(): Promise<void>;
+}
+
+export type ServiceCls<
+  RefName extends string = string,
+  
+  Methods = {},
+  
+  InjectMap extends { [key: string]: InjectInfo } = {},
+> = Cls<
+  Methods & ExtractInjectInfoObject<InjectMap> & Service,
+  {
+    readonly refName: RefName;
+    readonly type: ServiceType;
+    readonly [INJECT_META]: InjectMap;
+    readonly enabled: boolean;
+  }
+>;
+
+export function serve<RefName extends string, Injection extends InjectBuilder>(
+  refName: RefName,
+  injectBuilder: Injection,
+  ...extendSrvs: Cls[]
+): ServiceCls<RefName, {}, ReturnType<Injection>>;
+export function serve<RefName extends string, Injection extends InjectBuilder>(
+  refName: RefName,
+  option: ServiceOptions,
+  injectBuilder: Injection,
+  ...extendSrvs: Cls[]
+): ServiceCls<RefName, {}, ReturnType<Injection>>;
+export function serve<
+  T extends string,
+  Input,
+  Doc,
+  Model,
+  Obj,
+  Insight,
+  Filter extends FilterInstance,
+  Injection extends InjectBuilder,
+  LibSrvs extends Cls[] = [],
+>(
+  db: DatabaseModel<T, Input, Doc, Model, Obj, Insight, Filter>,
+  injectBuilder: Injection,
+  ...extendSrvs: LibSrvs
+): ServiceCls<T, DatabaseService<T, Input, Doc, Obj, Model, Insight, Filter, LibSrvs>, ReturnType<Injection>>;
+export function serve<
+  T extends string,
+  Input,
+  Doc,
+  Model,
+  Obj,
+  Insight,
+  Filter extends FilterInstance,
+  Injection extends InjectBuilder,
+  LibSrvs extends Cls[] = [],
+>(
+  db: DatabaseModel<T, Input, Doc, Model, Obj, Insight, Filter>,
+  injectBuilder: Injection,
+  ...extendSrvs: LibSrvs
+): ServiceCls<T, DatabaseService<T, Input, Doc, Obj, Model, Insight, Filter, LibSrvs>, ReturnType<Injection>>;
+export function serve<
+  T extends string,
+  Input,
+  Doc,
+  Model,
+  Obj,
+  Insight,
+  Filter extends FilterInstance,
+  Injection extends InjectBuilder,
+  LibSrvs extends ServiceCls[] = [],
+>(
+  db: DatabaseModel<T, Input, Doc, Model, Obj, Insight, Filter>,
+  option: ServiceOptions,
+  injectBuilder: Injection,
+  ...extendSrvs: LibSrvs
+): ServiceCls<T, DatabaseService<T, Input, Doc, Obj, Model, Insight, Filter, LibSrvs>, ReturnType<Injection>>;
+
+export function serve(
+  refNameOrDb: string | DatabaseModel,
+  optionOrInjectBuilder: ServiceOptions | InjectBuilder,
+  injectBuilderOrExtendSrv?: InjectBuilder<Exclude<InjectType, "database">> | Cls,
+  ...extendSrvs: Cls[]
+) {
+  const refName = typeof refNameOrDb === "string" ? lowerlize(refNameOrDb) : refNameOrDb.refName;
+  const option = typeof optionOrInjectBuilder === "object" ? optionOrInjectBuilder : { enabled: true };
+  const injectBuilder =
+    typeof optionOrInjectBuilder === "function" ? optionOrInjectBuilder : (injectBuilderOrExtendSrv as InjectBuilder);
+  const extSrvs = [
+    ...(typeof optionOrInjectBuilder === "function" && injectBuilderOrExtendSrv ? [injectBuilderOrExtendSrv] : []),
+    ...extendSrvs,
+  ] as ServiceCls[];
+  const isEnabled =
+    option.enabled ??
+    (!option.serverMode || process.env.SERVER_MODE === option.serverMode || process.env.SERVER_MODE === "all");
+  const serviceType = typeof refNameOrDb === "string" ? "plain" : "database";
+  const injectInfoMap = injectBuilder(injectionBuilder(refName));
+  if (serviceType === "database")
+    Object.assign(injectInfoMap, {
+      [`${refName}Model`]: new InjectInfo("database", { parentRefName: refName }),
+      __databaseModel: new InjectInfo("database", { parentRefName: refName }),
+    });
+  const srvRef = class Service {
+    static readonly type = serviceType;
+    static readonly refName = refName;
+    static enabled = isEnabled;
+    static get name() {
+      return `${capitalize(refName)}Service`;
+    }
+    static [INJECT_META] = {};
+    readonly logger = new Logger(this.constructor.name);
+    async onInit() {
+    }
+    async onDestroy() {
+    }
+  };
+  applyMixins(srvRef, extSrvs, avoidKeys);
+  Object.assign(srvRef[INJECT_META], ...extSrvs.map((srv) => srv[INJECT_META]), injectInfoMap);
+  const onInitFns = extSrvs.map((srv) => srv.prototype.onInit);
+  const onDestroyFns = extSrvs.map((srv) => srv.prototype.onDestroy);
+  Object.assign(srvRef.prototype, {
+    async _libsOnInit(this: Service) {
+      await Promise.all([...onInitFns.map((onInit) => onInit?.call(this)), this.onInit()]);
+    },
+    async _libsOnDestroy(this: Service) {
+      await Promise.all([...onDestroyFns.map((onDestroy) => onDestroy?.call(this)), this.onDestroy()]);
+    },
+  });
+
+  if (serviceType === "database") {
+    const preCreateFns = extSrvs.map((srv) => srv.prototype._preCreate);
+    const postCreateFns = extSrvs.map((srv) => srv.prototype._postCreate);
+    const preUpdateFns = extSrvs.map((srv) => srv.prototype._preUpdate);
+    const postUpdateFns = extSrvs.map((srv) => srv.prototype._postUpdate);
+    const preRemoveFns = extSrvs.map((srv) => srv.prototype._preRemove);
+    const postRemoveFns = extSrvs.map((srv) => srv.prototype._postRemove);
+    Object.assign(srvRef.prototype, {
+      async __libsPreCreate(this: DatabaseService, data: Parameters<DatabaseService["__libsPreCreate"]>[0]) {
+        let result = data;
+        for (const preCreate of preCreateFns) if (preCreate) result = await preCreate.call(this, result);
+        if (this._preCreate) result = await this._preCreate(result);
+        return result;
+      },
+      async __libsPostCreate(this: DatabaseService, doc: Parameters<DatabaseService["__libsPostCreate"]>[0]) {
+        let result = doc;
+        for (const postCreate of postCreateFns) if (postCreate) result = await postCreate.call(this, result);
+        if (this._postCreate) result = await this._postCreate(result);
+        return result;
+      },
+      async __libsPreUpdate(
+        this: DatabaseService,
+        id: string,
+        data: Parameters<DatabaseService["__libsPreUpdate"]>[1],
+      ) {
+        let result = data;
+        for (const preUpdate of preUpdateFns) if (preUpdate) result = await preUpdate.call(this, id, result);
+        if (this._preUpdate) result = await this._preUpdate(id, result);
+        return result;
+      },
+      async __libsPostUpdate(this: DatabaseService, doc: Parameters<DatabaseService["__libsPostUpdate"]>[0]) {
+        let result = doc;
+        for (const postUpdate of postUpdateFns) if (postUpdate) result = await postUpdate.call(this, result);
+        if (this._postUpdate) result = await this._postUpdate(result);
+        return result;
+      },
+      async __libsPreRemove(this: DatabaseService, id: string) {
+        for (const preRemove of preRemoveFns) await preRemove?.call(this, id);
+        if (this._preRemove) await this._preRemove(id);
+      },
+      async __libsPostRemove(this: DatabaseService, doc: Parameters<DatabaseService["__libsPostRemove"]>[0]) {
+        let result = doc;
+        for (const postRemove of postRemoveFns) if (postRemove) result = await postRemove.call(this, result);
+        if (this._postRemove) result = await this._postRemove(result);
+        return result;
+      },
+    });
+  }
+
+  return srvRef;
+}