@simplysm/service-server 13.0.100 → 14.0.1

package/docs/transport.md

@@ -1,164 +0,0 @@
-# Transport
-
-## WebSocket Transport
-
-### `WebSocketHandler`
-
-WebSocket handler interface. Manages multiple WebSocket connections, routes messages to services, and handles event broadcasting.
-
-```typescript
-interface WebSocketHandler {
-  addSocket(socket: WebSocket, clientId: string, clientName: string, connReq: FastifyRequest): void;
-  closeAll(): void;
-  broadcastReload(clientName: string | undefined, changedFileSet: Set<string>): Promise<void>;
-  emit<TInfo, TData>(
-    eventDef: ServiceEventDef<TInfo, TData>,
-    infoSelector: (item: TInfo) => boolean,
-    data: TData,
-  ): Promise<void>;
-}
-```
-
-| Method | Description |
-|--------|-------------|
-| `addSocket()` | Add a new WebSocket connection |
-| `closeAll()` | Close all active connections |
-| `broadcastReload()` | Broadcast reload message to all clients |
-| `emit()` | Emit event to matching clients |
-
-### `createWebSocketHandler`
-
-Create a WebSocket handler instance.
-
-```typescript
-function createWebSocketHandler(
-  runMethod: (def: {
-    serviceName: string;
-    methodName: string;
-    params: unknown[];
-    socket: ServiceSocket;
-  }) => Promise<unknown>,
-  jwtSecret?: string,
-): WebSocketHandler;
-```
-
-### `ServiceSocket`
-
-Service socket interface. Manages a single WebSocket connection with protocol encoding/decoding, ping/pong keep-alive, and event listener tracking.
-
-```typescript
-interface ServiceSocket {
-  readonly connectedAtDateTime: DateTime;
-  readonly clientName: string;
-  readonly connReq: FastifyRequest;
-  authTokenPayload?: AuthTokenPayload;
-
-  close(): void;
-  send(uuid: string, msg: ServiceServerMessage): Promise<number>;
-  addListener(key: string, eventName: string, info: unknown): void;
-  removeListener(key: string): void;
-  getEventListeners(eventName: string): Array<{ key: string; info: unknown }>;
-  filterEventTargetKeys(targetKeys: string[]): string[];
-  on(event: "error", handler: (err: Error) => void): void;
-  on(event: "close", handler: (code: number) => void): void;
-  on(event: "message", handler: (data: { uuid: string; msg: ServiceClientMessage }) => void): void;
-}
-```
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `connectedAtDateTime` | `DateTime` | Connection time |
-| `clientName` | `string` | Client name |
-| `connReq` | `FastifyRequest` | Original Fastify request |
-| `authTokenPayload` | `AuthTokenPayload` | Authenticated token payload |
-
-| Method | Description |
-|--------|-------------|
-| `close()` | Close the WebSocket connection |
-| `send()` | Send a message to the client |
-| `addListener()` | Register an event listener |
-| `removeListener()` | Remove an event listener |
-| `getEventListeners()` | Get all listeners for an event name |
-| `filterEventTargetKeys()` | Filter target keys that exist in this socket |
-| `on()` | Register event handlers (error, close, message) |
-
-### `createServiceSocket`
-
-Create a service socket instance.
-
-```typescript
-function createServiceSocket(
-  socket: WebSocket,
-  clientId: string,
-  clientName: string,
-  connReq: FastifyRequest,
-): ServiceSocket;
-```
-
-## HTTP Transport
-
-### `handleHttpRequest`
-
-Handle HTTP API requests. Routes `POST/GET /api/:service/:method` to service methods.
-
-```typescript
-async function handleHttpRequest<TAuthInfo = unknown>(
-  req: FastifyRequest,
-  reply: FastifyReply,
-  jwtSecret: string | undefined,
-  runMethod: (def: {
-    serviceName: string;
-    methodName: string;
-    params: unknown[];
-    http: { clientName: string; authTokenPayload?: AuthTokenPayload<TAuthInfo> };
-  }) => Promise<unknown>,
-): Promise<void>;
-```
-
-### `handleUpload`
-
-Handle file upload requests. Accepts multipart form data with auth token.
-
-```typescript
-async function handleUpload(
-  req: FastifyRequest,
-  reply: FastifyReply,
-  rootPath: string,
-  jwtSecret: string | undefined,
-): Promise<void>;
-```
-
-### `handleStaticFile`
-
-Handle static file serving. Serves files from `www/` directory with security checks (path traversal protection, hidden file blocking).
-
-```typescript
-async function handleStaticFile(
-  req: FastifyRequest,
-  reply: FastifyReply,
-  rootPath: string,
-  urlPath: string,
-): Promise<void>;
-```
-
-## Protocol
-
-### `ServerProtocolWrapper`
-
-Server-side protocol wrapper interface. Automatically offloads heavy encoding/decoding to a worker thread (>30KB threshold).
-
-```typescript
-interface ServerProtocolWrapper {
-  encode(uuid: string, message: ServiceMessage): Promise<{ chunks: Bytes[]; totalSize: number }>;
-  decode(bytes: Bytes): Promise<ServiceMessageDecodeResult<ServiceMessage>>;
-  dispose(): void;
-}
-```
-
-### `createServerProtocolWrapper`
-
-Create a server protocol wrapper instance.
-
-```typescript
-function createServerProtocolWrapper(): ServerProtocolWrapper;
-```

package/src/services/smtp-client-service.ts

@@ -1,59 +0,0 @@
-import nodemailer from "nodemailer";
-import { defineService, type ServiceMethods } from "../core/define-service";
-import type {
-  SmtpClientDefaultOptions,
-  SmtpClientSendByDefaultOption,
-  SmtpClientSendOption,
-} from "@simplysm/service-common";
-
-export const SmtpClientService = defineService("SmtpClient", (ctx) => ({
-  async send(options: SmtpClientSendOption): Promise<string> {
-    return new Promise<string>((resolve, reject) => {
-      const transport = nodemailer.createTransport({
-        host: options.host,
-        port: options.port,
-        secure: options.secure,
-        auth:
-          options.user != null
-            ? {
-                user: options.user,
-                pass: options.pass,
-              }
-            : undefined,
-        tls: {
-          rejectUnauthorized: false,
-        },
-      });
-
-      transport.sendMail(options as nodemailer.SendMailOptions, (err, info) => {
-        if (err) {
-          reject(err);
-          return;
-        }
-
-        resolve(info.messageId);
-      });
-    });
-  },
-
-  async sendByConfig(configName: string, options: SmtpClientSendByDefaultOption): Promise<string> {
-    const config = (
-      await ctx.getConfig<Record<string, SmtpClientDefaultOptions | undefined>>("smtp")
-    )[configName];
-    if (config == null) {
-      throw new Error(`SMTP config not found: ${configName}`);
-    }
-
-    return this.send({
-      user: config.user,
-      pass: config.pass,
-      host: config.host,
-      port: config.port,
-      secure: config.secure,
-      from: `"${config.senderName}" <${config.senderEmail ?? config.user}>`,
-      ...options,
-    });
-  },
-}));
-
-export type SmtpClientServiceType = ServiceMethods<typeof SmtpClientService>;

package/tests/define-service.spec.ts

@@ -1,66 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { defineService, auth, getServiceAuthPermissions } from "@simplysm/service-server";
-
-describe("defineService", () => {
-  it("creates service definition with name and factory", () => {
-    const svc = defineService("Health", (_ctx) => ({
-      check: () => "ok",
-    }));
-
-    expect(svc.name).toBe("Health");
-    expect(typeof svc.factory).toBe("function");
-  });
-
-  it("factory generates methods when called with context", () => {
-    const svc = defineService("Echo", (_ctx) => ({
-      echo: (msg: string) => `Echo: ${msg}`,
-    }));
-
-    const methods = svc.factory({} as any);
-    expect(methods.echo("hello")).toBe("Echo: hello");
-  });
-});
-
-describe("Authentication", () => {
-  it("marks function with empty permissions (login required only)", () => {
-    const fn = auth(() => "result");
-    expect(getServiceAuthPermissions(fn)).toEqual([]);
-    expect(fn()).toBe("result");
-  });
-
-  it("marks function with specific permissions", () => {
-    const fn = auth(["admin"], (id: number) => id * 2);
-    expect(getServiceAuthPermissions(fn)).toEqual(["admin"]);
-    expect(fn(5)).toBe(10);
-  });
-
-  it("returns undefined for unmarked function", () => {
-    const fn = () => "plain";
-    expect(getServiceAuthPermissions(fn)).toBeUndefined();
-  });
-
-  it("works at service level (factory wrapping)", () => {
-    const svc = defineService(
-      "User",
-      auth((_ctx) => ({
-        getProfile: () => "profile",
-      })),
-    );
-
-    expect(svc.authPermissions).toEqual([]);
-  });
-
-  it("method-level auth is readable from returned methods", () => {
-    const svc = defineService(
-      "Mixed",
-      auth((_ctx) => ({
-        normal: () => "normal",
-        adminOnly: auth(["admin"], () => "admin"),
-      })),
-    );
-
-    const methods = svc.factory({} as any);
-    expect(getServiceAuthPermissions(methods.normal)).toBeUndefined();
-    expect(getServiceAuthPermissions(methods.adminOnly)).toEqual(["admin"]);
-  });
-});

package/tests/orm-service.spec.ts

@@ -1,83 +0,0 @@
-import { describe, it, expect, vi, beforeEach } from "vitest";
-import type { QueryDef } from "@simplysm/orm-common";
-
-vi.mock("@simplysm/orm-node", () => ({
-  createDbConn: vi.fn(),
-}));
-
-import { createDbConn } from "@simplysm/orm-node";
-import { OrmService } from "../src/services/orm-service";
-
-describe("OrmService.executeDefs", () => {
-  let mockExecute: ReturnType<typeof vi.fn>;
-  let methods: any;
-  let connId: number;
-
-  const twoDefs: QueryDef[] = [
-    {
-      type: "createTable",
-      table: { database: "db", name: "A" },
-      columns: [{ name: "id", dataType: { type: "bigint" } }],
-      primaryKey: ["id"],
-    },
-    {
-      type: "createTable",
-      table: { database: "db", name: "B" },
-      columns: [{ name: "id", dataType: { type: "bigint" } }],
-      primaryKey: ["id"],
-    },
-  ];
-
-  beforeEach(async () => {
-    mockExecute = vi.fn((queries: string[]) => Promise.resolve(queries.map(() => [])));
-
-    const mockConn = {
-      config: { dialect: "postgresql" as const },
-      isConnected: true,
-      connect: vi.fn(),
-      close: vi.fn(),
-      execute: mockExecute,
-      executeParametrized: vi.fn(),
-      bulkInsert: vi.fn(),
-      beginTransaction: vi.fn(),
-      commitTransaction: vi.fn(),
-      rollbackTransaction: vi.fn(),
-      on: vi.fn(),
-    };
-
-    vi.mocked(createDbConn).mockResolvedValue(mockConn as any);
-
-    const ctx = {
-      socket: { on: vi.fn() },
-      getConfig: vi.fn(() =>
-        Promise.resolve({
-          test: { dialect: "postgresql", host: "localhost", database: "db" },
-        }),
-      ),
-      clientName: "test",
-    };
-
-    methods = OrmService.factory(ctx as any);
-    connId = await methods.connect({ configName: "test" });
-    mockExecute.mockClear();
-  });
-
-  it("executes queries individually when options is undefined", async () => {
-    const result = await methods.executeDefs(connId, twoDefs);
-
-    // Should pass 2 separate queries, not 1 combined string
-    expect(mockExecute).toHaveBeenCalledTimes(1);
-    expect(mockExecute.mock.calls[0][0]).toHaveLength(2);
-
-    // Should return one result per def
-    expect(result).toHaveLength(2);
-  });
-
-  it("combines queries when options is explicitly all-null", async () => {
-    await methods.executeDefs(connId, twoDefs, [undefined, undefined]);
-
-    // Should pass 1 combined query string
-    expect(mockExecute).toHaveBeenCalledTimes(1);
-    expect(mockExecute.mock.calls[0][0]).toHaveLength(1);
-  });
-});

package/tests/service-executor.spec.ts

@@ -1,114 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { executeServiceMethod } from "../src/core/service-executor";
-import { defineService, auth } from "../src/core/define-service";
-
-// Minimal mock server
-function createMockServer(services: any[]) {
-  return { options: { services, auth: { jwtSecret: "test" } } } as any;
-}
-
-describe("executeServiceMethod with ServiceDefinition", () => {
-  it("executes a basic service method", async () => {
-    const EchoService = defineService("Echo", (_ctx) => ({
-      echo: (msg: string) => `Echo: ${msg}`,
-    }));
-
-    const server = createMockServer([EchoService]);
-    const result = await executeServiceMethod(server, {
-      serviceName: "Echo",
-      methodName: "echo",
-      params: ["hello"],
-    });
-
-    expect(result).toBe("Echo: hello");
-  });
-
-  it("throws error when service not found", async () => {
-    const server = createMockServer([]);
-
-    await expect(
-      executeServiceMethod(server, { serviceName: "Unknown", methodName: "test", params: [] }),
-    ).rejects.toThrow("Service [Unknown] not found.");
-  });
-
-  it("throws error when method not found", async () => {
-    const svc = defineService("Test", (_ctx) => ({
-      existing: () => "ok",
-    }));
-    const server = createMockServer([svc]);
-
-    await expect(
-      executeServiceMethod(server, { serviceName: "Test", methodName: "nonexistent", params: [] }),
-    ).rejects.toThrow("Method [Test.nonexistent] not found.");
-  });
-
-  it("blocks unauthenticated access to auth-required service", async () => {
-    const svc = defineService(
-      "Protected",
-      auth((_ctx) => ({
-        secret: () => "secret",
-      })),
-    );
-    const server = createMockServer([svc]);
-
-    await expect(
-      executeServiceMethod(server, { serviceName: "Protected", methodName: "secret", params: [] }),
-    ).rejects.toThrow("Login is required.");
-  });
-
-  it("blocks unauthorized role access", async () => {
-    const svc = defineService(
-      "Admin",
-      auth((_ctx) => ({
-        manage: auth(["admin"], () => "managed"),
-        view: () => "viewed",
-      })),
-    );
-    const server = createMockServer([svc]);
-
-    // Has auth but wrong role
-    await expect(
-      executeServiceMethod(server, {
-        serviceName: "Admin",
-        methodName: "manage",
-        params: [],
-        http: { clientName: "test", authTokenPayload: { roles: ["user"], data: {} } as any },
-      }),
-    ).rejects.toThrow("Insufficient permissions.");
-  });
-
-  it("allows access with correct role", async () => {
-    const svc = defineService(
-      "Admin",
-      auth((_ctx) => ({
-        manage: auth(["admin"], () => "managed"),
-      })),
-    );
-    const server = createMockServer([svc]);
-
-    const result = await executeServiceMethod(server, {
-      serviceName: "Admin",
-      methodName: "manage",
-      params: [],
-      http: { clientName: "test", authTokenPayload: { roles: ["admin"], data: {} } as any },
-    });
-
-    expect(result).toBe("managed");
-  });
-
-  it("provides context to factory", async () => {
-    const svc = defineService("Ctx", (ctx) => ({
-      getClientName: () => ctx.clientName,
-    }));
-    const server = createMockServer([svc]);
-
-    const result = await executeServiceMethod(server, {
-      serviceName: "Ctx",
-      methodName: "getClientName",
-      params: [],
-      http: { clientName: "my-app", authTokenPayload: undefined },
-    });
-
-    expect(result).toBe("my-app");
-  });
-});