@simplysm/service-server 14.0.4 → 14.0.5

package/docs/service-definition.md

@@ -0,0 +1,151 @@
+# Service Definition/Context
+
+## `ServiceContext`
+
+Service execution context providing access to the server, socket, authentication info, and configuration.
+
+```typescript
+export interface ServiceContext<TAuthInfo = unknown> {
+  server: ServiceServer<TAuthInfo>;
+  socket?: ServiceSocket;
+  http?: {
+    clientName: string;
+    authTokenPayload?: AuthTokenPayload<TAuthInfo>;
+  };
+  legacy?: {
+    clientName?: string;
+  };
+
+  get authInfo(): TAuthInfo | undefined;
+  get clientName(): string | undefined;
+  get clientPath(): string | undefined;
+  getConfig<T>(section: string): Promise<T>;
+}
+```
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `server` | `ServiceServer<TAuthInfo>` | The server instance |
+| `socket` | `ServiceSocket?` | WebSocket connection (undefined for HTTP requests) |
+| `http` | `{ clientName: string; authTokenPayload?: AuthTokenPayload<TAuthInfo> }?` | HTTP request context (undefined for WebSocket requests) |
+| `legacy` | `{ clientName?: string }?` | V1 legacy context (auto-update only) |
+| `authInfo` | `TAuthInfo \| undefined` (getter) | Authenticated user data from socket or HTTP auth token |
+| `clientName` | `string \| undefined` (getter) | Client name from socket, HTTP, or legacy context. Validates against path traversal |
+| `clientPath` | `string \| undefined` (getter) | Resolved client path: `{rootPath}/www/{clientName}` |
+| `getConfig<T>(section)` | `(section: string) => Promise<T>` | Loads config section from root and client `.config.json` files (merged) |
+
+## `createServiceContext`
+
+Creates a `ServiceContext` instance.
+
+```typescript
+export function createServiceContext<TAuthInfo = unknown>(
+  server: ServiceServer<TAuthInfo>,
+  socket?: ServiceSocket,
+  http?: { clientName: string; authTokenPayload?: AuthTokenPayload<TAuthInfo> },
+  legacy?: { clientName?: string },
+): ServiceContext<TAuthInfo>;
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `server` | `ServiceServer<TAuthInfo>` | The server instance |
+| `socket` | `ServiceSocket?` | WebSocket connection |
+| `http` | `{ clientName: string; authTokenPayload?: AuthTokenPayload<TAuthInfo> }?` | HTTP request context |
+| `legacy` | `{ clientName?: string }?` | V1 legacy context |
+
+## `getServiceAuthPermissions`
+
+Reads auth permissions from a function wrapped by `auth()`. Returns `undefined` for unwrapped functions.
+
+```typescript
+export function getServiceAuthPermissions(fn: Function): string[] | undefined;
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `fn` | `Function` | The function to check for auth permissions |
+
+**Returns:** `string[] | undefined` -- Permission array if auth-wrapped, `undefined` otherwise.
+
+## `auth`
+
+Authentication wrapper for service factories and methods. Marks functions as requiring authentication, optionally with specific role permissions.
+
+```typescript
+// No role restriction (login required)
+export function auth<TFunction extends (...args: any[]) => any>(fn: TFunction): TFunction;
+
+// Role restriction (specific roles required)
+export function auth<TFunction extends (...args: any[]) => any>(
+  permissions: string[],
+  fn: TFunction,
+): TFunction;
+```
+
+Usage levels:
+- **Service level:** `auth((ctx) => ({ ... }))` -- All methods require login
+- **Service level with roles:** `auth(["admin"], (ctx) => ({ ... }))` -- All methods require specific roles
+- **Method level:** `auth(() => result)` -- Specific method requires login
+- **Method level with roles:** `auth(["admin"], () => result)` -- Specific method requires specific roles
+
+## `ServiceDefinition`
+
+Service definition with a name and factory function.
+
+```typescript
+export interface ServiceDefinition<TMethods = Record<string, (...args: any[]) => any>> {
+  name: string;
+  factory: (ctx: ServiceContext) => TMethods;
+  authPermissions?: string[];
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `string` | Service name (used in RPC routing) |
+| `factory` | `(ctx: ServiceContext) => TMethods` | Factory function that creates service methods from a context |
+| `authPermissions` | `string[]?` | Service-level auth permissions (extracted from `auth()` wrapper) |
+
+## `defineService`
+
+Defines a named service with a factory function.
+
+```typescript
+export function defineService<TMethods extends Record<string, (...args: any[]) => any>>(
+  name: string,
+  factory: (ctx: ServiceContext) => TMethods,
+): ServiceDefinition<TMethods>;
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `name` | `string` | Service name |
+| `factory` | `(ctx: ServiceContext) => TMethods` | Factory function creating service methods |
+
+**Returns:** `ServiceDefinition<TMethods>`
+
+**Example:**
+
+```typescript
+const UserService = defineService("User", auth((ctx) => ({
+  getProfile: () => ctx.authInfo,
+  adminOnly: auth(["admin"], () => "admin-data"),
+})));
+```
+
+## `ServiceMethods`
+
+Type utility that extracts method signatures from a `ServiceDefinition`. Useful for sharing types between server and client.
+
+```typescript
+export type ServiceMethods<TDefinition> =
+  TDefinition extends ServiceDefinition<infer M> ? M : never;
+```
+
+**Example:**
+
+```typescript
+export type UserServiceType = ServiceMethods<typeof UserService>;
+// Client: client.getService<UserServiceType>("User");
+```

package/docs/service-executor.md

@@ -0,0 +1,42 @@
+# Service Executor
+
+## `executeServiceMethod`
+
+Executes a service method with full validation and authentication checking.
+
+```typescript
+export async function executeServiceMethod(
+  server: ServiceServer,
+  def: {
+    serviceName: string;
+    methodName: string;
+    params: unknown[];
+    socket?: ServiceSocket;
+    http?: { clientName: string; authTokenPayload?: AuthTokenPayload };
+  },
+): Promise<unknown>;
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `server` | `ServiceServer` | The server instance (used to find service definitions and check auth config) |
+| `def.serviceName` | `string` | Service name to look up |
+| `def.methodName` | `string` | Method name to invoke |
+| `def.params` | `unknown[]` | Method parameters |
+| `def.socket` | `ServiceSocket?` | WebSocket connection (for WebSocket requests) |
+| `def.http` | `{ clientName: string; authTokenPayload?: AuthTokenPayload }?` | HTTP context (for HTTP requests) |
+
+**Returns:** `Promise<unknown>` -- The method return value.
+
+**Execution flow:**
+1. Finds the service definition by name (throws if not found)
+2. Validates client name for path traversal attacks
+3. Creates a `ServiceContext`
+4. Calls the factory to create the method object
+5. Looks up the method by name (throws if not a function)
+6. Checks authentication:
+   - Method-level `auth()` permissions take precedence over service-level
+   - If `server.options.auth === undefined` and auth is required, throws configuration error
+   - If `server.options.auth === false`, skips all auth checks
+   - Otherwise, verifies `authTokenPayload` exists and has required roles
+7. Invokes the method with parameters

package/docs/service-server.md

@@ -0,0 +1,80 @@
+# Main ServiceServer
+
+## `ServiceServer`
+
+Main server class built on Fastify with WebSocket support, JWT authentication, and graceful shutdown. Extends `EventEmitter` with `ready` and `close` events.
+
+```typescript
+export class ServiceServer<TAuthInfo = unknown> extends EventEmitter<{
+  ready: void;
+  close: void;
+}> {
+  constructor(options: ServiceServerOptions);
+}
+```
+
+### Events
+
+| Event | Data Type | Description |
+|-------|-----------|-------------|
+| `ready` | `void` | Emitted when the server starts listening |
+| `close` | `void` | Emitted when the server is closed |
+
+### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `options` | `ServiceServerOptions` (readonly) | Server configuration options |
+| `fastify` | `FastifyInstance` (readonly) | The underlying Fastify instance for custom route registration |
+| `isOpen` | `boolean` | Whether the server is currently listening |
+
+### Methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `listen` | `listen(): Promise<void>` | Starts the server. Registers all plugins, routes, and WebSocket handlers. Listens on `0.0.0.0:{port}` |
+| `close` | `close(): Promise<void>` | Closes all WebSocket connections and stops the Fastify server |
+| `emitEvent` | `emitEvent<TInfo, TData>(eventDef: ServiceEventDef<TInfo, TData>, infoSelector: (item: TInfo) => boolean, data: TData): Promise<void>` | Broadcasts an event to connected clients matching the info selector |
+| `signAuthToken` | `signAuthToken(payload: AuthTokenPayload<TAuthInfo>): Promise<string>` | Signs a JWT token using the server's secret |
+| `verifyAuthToken` | `verifyAuthToken(token: string): Promise<AuthTokenPayload<TAuthInfo>>` | Verifies a JWT token using the server's secret |
+
+### Registered Routes
+
+| Route | Method | Description |
+|-------|--------|-------------|
+| `/api/:service/:method` | GET, POST | HTTP RPC endpoint |
+| `/upload` | POST | Multipart file upload endpoint |
+| `/` | WebSocket | WebSocket endpoint (V1 and V2) |
+| `/ws` | WebSocket | WebSocket endpoint (V1 and V2) |
+| `/*` | GET, POST, PUT, DELETE, PATCH, HEAD | Static file handler |
+
+### Registered Plugins
+
+- `@fastify/websocket` -- WebSocket support
+- `@fastify/helmet` -- Security headers (CSP configured for permissive defaults)
+- `@fastify/multipart` -- File upload support
+- `@fastify/static` -- Static file serving (manual serving via handler)
+- `@fastify/cors` -- Cross-origin support (allows all origins)
+
+### Graceful Shutdown
+
+Registers `SIGINT` and `SIGTERM` handlers that:
+1. Close all WebSocket connections
+2. Stop the Fastify server
+3. Force exit after 10 seconds if shutdown hangs
+
+## `createServiceServer`
+
+Factory function to create a `ServiceServer` instance.
+
+```typescript
+export function createServiceServer<TAuthInfo = unknown>(
+  options: ServiceServerOptions,
+): ServiceServer<TAuthInfo>;
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `options` | `ServiceServerOptions` | Server configuration options |
+
+**Returns:** `ServiceServer<TAuthInfo>`

package/docs/service-socket.md

@@ -0,0 +1,73 @@
+# Service Socket
+
+## `ServiceSocket`
+
+Manages a single WebSocket connection with protocol encoding/decoding, ping/pong keepalive, and event listener tracking.
+
+```typescript
+export 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;
+}
+```
+
+### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `connectedAtDateTime` | `DateTime` (readonly) | Timestamp when the connection was established |
+| `clientName` | `string` (readonly) | Client identifier name |
+| `connReq` | `FastifyRequest` (readonly) | Original Fastify request object |
+| `authTokenPayload` | `AuthTokenPayload?` | Authenticated token payload (set via auth message) |
+
+### Methods
+
+| Method | Parameters | Return | Description |
+|--------|-----------|--------|-------------|
+| `close` | none | `void` | Terminates the WebSocket connection |
+| `send` | `uuid: string, msg: ServiceServerMessage` | `Promise<number>` | Sends a message to the client. Returns total bytes sent |
+| `addListener` | `key: string, eventName: string, info: unknown` | `void` | Registers an event listener |
+| `removeListener` | `key: string` | `void` | Removes an event listener by key |
+| `getEventListeners` | `eventName: string` | `Array<{ key: string; info: unknown }>` | Gets all listeners for an event name |
+| `filterEventTargetKeys` | `targetKeys: string[]` | `string[]` | Filters target keys that exist in this socket's listeners |
+| `on("error")` | `handler: (err: Error) => void` | `void` | Registers error event handler |
+| `on("close")` | `handler: (code: number) => void` | `void` | Registers close event handler |
+| `on("message")` | `handler: (data: { uuid: string; msg: ServiceClientMessage }) => void` | `void` | Registers message event handler |
+
+## `createServiceSocket`
+
+Creates a `ServiceSocket` instance wrapping a raw WebSocket.
+
+```typescript
+export function createServiceSocket(
+  socket: WebSocket,
+  clientId: string,
+  clientName: string,
+  connReq: FastifyRequest,
+): ServiceSocket;
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `socket` | `WebSocket` (from `ws`) | Raw WebSocket connection |
+| `clientId` | `string` | Client unique identifier |
+| `clientName` | `string` | Client name |
+| `connReq` | `FastifyRequest` | Original request object |
+
+Internal behavior:
+- Ping interval: 5 seconds (terminates connection if no pong response)
+- Responds to client ping (`0x01`) with pong (`0x02`)
+- Uses `ServerProtocolWrapper` for encode/decode
+- Reports chunk progress back to client during message reassembly

package/docs/websocket-handler.md

@@ -0,0 +1,58 @@
+# WebSocket Handler
+
+## `WebSocketHandler`
+
+Manages multiple WebSocket connections, routes messages to services, and handles event broadcasting.
+
+```typescript
+export interface WebSocketHandler {
+  addSocket(
+    socket: WebSocket,
+    clientId: string,
+    clientName: string,
+    connReq: FastifyRequest,
+  ): void;
+  closeAll(): void;
+  emit<TInfo, TData>(
+    eventDef: ServiceEventDef<TInfo, TData>,
+    infoSelector: (item: TInfo) => boolean,
+    data: TData,
+  ): Promise<void>;
+}
+```
+
+| Method | Parameters | Return | Description |
+|--------|-----------|--------|-------------|
+| `addSocket` | `socket: WebSocket, clientId: string, clientName: string, connReq: FastifyRequest` | `void` | Registers a new WebSocket connection. Closes any existing connection with the same `clientId` |
+| `closeAll` | none | `void` | Closes all active WebSocket connections |
+| `emit` | `eventDef: ServiceEventDef<TInfo, TData>, infoSelector: (item: TInfo) => boolean, data: TData` | `Promise<void>` | Broadcasts an event to all sockets that have matching event listeners |
+
+## `createWebSocketHandler`
+
+Creates a `WebSocketHandler` instance.
+
+```typescript
+export function createWebSocketHandler(
+  runMethod: (def: {
+    serviceName: string;
+    methodName: string;
+    params: unknown[];
+    socket?: ServiceSocket;
+  }) => Promise<unknown>,
+  jwtSecret: string | undefined,
+): WebSocketHandler;
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `runMethod` | `(def: { serviceName; methodName; params; socket? }) => Promise<unknown>` | Callback to execute service methods |
+| `jwtSecret` | `string \| undefined` | JWT secret for auth message verification |
+
+Message routing:
+- `${service}.${method}` -- Invokes `runMethod` and sends response
+- `evt:add` -- Registers an event listener on the socket
+- `evt:remove` -- Removes an event listener from the socket
+- `evt:gets` -- Returns all listener infos for an event name across all sockets
+- `evt:emit` -- Dispatches an event to target listener keys across all sockets
+- `auth` -- Verifies JWT token and stores payload on the socket
+- Other -- Returns `BAD_MESSAGE` error

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/service-server",
-  "version": "14.0.4",
+  "version": "14.0.5",
   "description": "심플리즘 패키지 - 서비스 (server)",
   "author": "심플리즘",
   "license": "Apache-2.0",
@@ -35,11 +35,11 @@
     "semver": "^7.7.4",
     "utf-8-validate": "^6.0.6",
     "ws": "^8.20.0",
-    "@simplysm/core-common": "14.0.4",
-    "@simplysm/orm-common": "14.0.4",
-    "@simplysm/orm-node": "14.0.4",
-    "@simplysm/service-common": "14.0.4",
-    "@simplysm/core-node": "14.0.4"
+    "@simplysm/orm-common": "14.0.5",
+    "@simplysm/core-common": "14.0.5",
+    "@simplysm/service-common": "14.0.5",
+    "@simplysm/orm-node": "14.0.5",
+    "@simplysm/core-node": "14.0.5"
   },
   "devDependencies": {
     "@types/nodemailer": "^7.0.11",

package/docs/core.md

@@ -1,192 +0,0 @@
-# Core
-
-Service definition, context, authentication wrapper, and method execution.
-
-## ServiceContext\<TAuthInfo\>
-
-Context object passed to service factory functions. Provides access to the server, socket, HTTP info, and authentication state.
-
-```ts
-interface ServiceContext<TAuthInfo = unknown> {
-  server: ServiceServer<TAuthInfo>;
-  socket?: ServiceSocket;
-  http?: {
-    clientName: string;
-    authTokenPayload?: AuthTokenPayload<TAuthInfo>;
-  };
-  legacy?: {
-    clientName?: string;
-  };
-  get authInfo(): TAuthInfo | undefined;
-  get clientName(): string | undefined;
-  get clientPath(): string | undefined;
-  getConfig<T>(section: string): Promise<T>;
-}
-```
-
-| Member | Kind | Type | Description |
-|--------|------|------|-------------|
-| `server` | property | `ServiceServer<TAuthInfo>` | Reference to the server instance |
-| `socket` | property | `ServiceSocket?` | WebSocket connection (present for WS calls) |
-| `http` | property | `{ clientName; authTokenPayload? }?` | HTTP request info (present for HTTP calls) |
-| `http.clientName` | field | `string` | Client identifier from HTTP header |
-| `http.authTokenPayload` | field | `AuthTokenPayload<TAuthInfo>?` | Decoded auth token from HTTP request |
-| `legacy` | property | `{ clientName? }?` | Legacy V1 connection info |
-| `authInfo` | getter | `TAuthInfo \| undefined` | Authenticated user data (from socket or HTTP token) |
-| `clientName` | getter | `string \| undefined` | Client name (from socket, HTTP, or legacy) |
-| `clientPath` | getter | `string \| undefined` | Client path identifier |
-| `getConfig` | method | `<T>(section: string) => Promise<T>` | Read a configuration section |
-
-## createServiceContext
-
-Create a `ServiceContext` instance.
-
-```ts
-function createServiceContext<TAuthInfo = unknown>(
-  server: ServiceServer<TAuthInfo>,
-  socket?: ServiceSocket,
-  http?: { clientName: string; authTokenPayload?: AuthTokenPayload<TAuthInfo> },
-  legacy?: { clientName?: string },
-): ServiceContext<TAuthInfo>;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `server` | `ServiceServer<TAuthInfo>` | Server instance |
-| `socket` | `ServiceSocket?` | WebSocket connection |
-| `http` | `{ clientName; authTokenPayload? }?` | HTTP request context |
-| `legacy` | `{ clientName? }?` | Legacy V1 context |
-
-## auth
-
-Authentication wrapper for service factories and methods. Marks a function as requiring authentication. Optionally restricts access to specific roles.
-
-```ts
-// No role restriction -- just requires authentication
-function auth<TFunction extends (...args: any[]) => any>(fn: TFunction): TFunction;
-
-// With role restriction
-function auth<TFunction extends (...args: any[]) => any>(permissions: string[], fn: TFunction): TFunction;
-```
-
-Can be applied at the service level (wrapping the factory) or at individual method level.
-
-```ts
-const MyService = defineService("My", (ctx) => ({
-  // Public method -- no auth required
-  publicMethod() { return "open"; },
-
-  // Requires authentication (any role)
-  protectedMethod: auth(() => "protected"),
-
-  // Requires "admin" role
-  adminMethod: auth(["admin"], () => "admin only"),
-}));
-```
-
-## getServiceAuthPermissions
-
-Read the authentication permissions from a function wrapped with `auth()`. Returns `undefined` if the function is not wrapped.
-
-```ts
-function getServiceAuthPermissions(fn: Function): string[] | undefined;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `fn` | `Function` | A potentially auth-wrapped function |
-
-Returns `string[]` (role list, possibly empty for auth-only) or `undefined` (not wrapped).
-
-## ServiceDefinition\<TMethods\>
-
-A named service with a factory function and optional auth permissions.
-
-```ts
-interface ServiceDefinition<TMethods = Record<string, (...args: any[]) => any>> {
-  name: string;
-  factory: (ctx: ServiceContext) => TMethods;
-  authPermissions?: string[];
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `name` | `string` | Service name used for RPC routing |
-| `factory` | `(ctx: ServiceContext) => TMethods` | Factory function that creates service methods |
-| `authPermissions` | `string[]?` | Service-level auth permissions (from `auth()` wrapper) |
-
-## defineService
-
-Define a named service from a factory function.
-
-```ts
-function defineService<TMethods extends Record<string, (...args: any[]) => any>>(
-  name: string,
-  factory: (ctx: ServiceContext) => TMethods,
-): ServiceDefinition<TMethods>;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `name` | `string` | Service name |
-| `factory` | `(ctx: ServiceContext) => TMethods` | Factory that receives context and returns methods |
-
-```ts
-const UserService = defineService("User", (ctx) => ({
-  async getUser(id: number) {
-    // ctx.authInfo, ctx.server, ctx.getConfig, etc.
-    return { id, name: "Alice" };
-  },
-}));
-```
-
-## ServiceMethods\<TDefinition\>
-
-Utility type that extracts method signatures from a `ServiceDefinition`. Useful for sharing types with the client.
-
-```ts
-type ServiceMethods<TDefinition> = TDefinition extends ServiceDefinition<infer M> ? M : never;
-```
-
-```ts
-// Server
-const UserService = defineService("User", (ctx) => ({
-  getUser(id: number) { return { id, name: "Alice" }; },
-}));
-
-// Shared type for client
-type UserServiceType = ServiceMethods<typeof UserService>;
-
-// Client
-const userSvc = client.getService<UserServiceType>("User");
-const user = await userSvc.getUser(1); // typed as { id: number; name: string }
-```
-
-## executeServiceMethod
-
-Execute a service method by name. Used internally by the transport layer; can also be called directly for testing or custom routing.
-
-```ts
-async function executeServiceMethod(
-  server: ServiceServer,
-  def: {
-    serviceName: string;
-    methodName: string;
-    params: unknown[];
-    socket?: ServiceSocket;
-    http?: { clientName: string; authTokenPayload?: AuthTokenPayload };
-  },
-): Promise<unknown>;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `server` | `ServiceServer` | Server instance containing registered services |
-| `def.serviceName` | `string` | Name of the service to invoke |
-| `def.methodName` | `string` | Method name within the service |
-| `def.params` | `unknown[]` | Method arguments |
-| `def.socket` | `ServiceSocket?` | WebSocket context (for WS calls) |
-| `def.http` | `{ clientName; authTokenPayload? }?` | HTTP context (for HTTP calls) |
-
-Returns the method return value.

package/docs/legacy.md

@@ -1,21 +0,0 @@
-# Legacy
-
-## handleV1Connection
-
-V1 legacy client handler. Only supports auto-update requests; all other requests receive an upgrade-required error.
-
-```ts
-function handleV1Connection(
-  socket: WebSocket,
-  autoUpdateMethods: { getLastVersion: (platform: string) => Promise<any> },
-  clientNameSetter?: (clientName: string | undefined) => void,
-): void;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `socket` | `WebSocket` | Raw WebSocket connection from the V1 client |
-| `autoUpdateMethods` | `{ getLastVersion: (platform: string) => Promise<any> }` | Auto-update method implementation |
-| `clientNameSetter` | `((clientName: string \| undefined) => void)?` | Optional callback invoked with the client name when connected (or `undefined` on disconnect) |
-
-This handler is provided for backward compatibility with V1 protocol clients. New clients should use the V2 binary protocol.