@logux/server 0.13.1 → 0.15.0

package/base-server/index.d.ts

@@ -19,11 +19,19 @@ import type {
   IncomingMessage,
   ServerResponse
 } from 'node:http'
-import type { LogFn } from 'pino'
+import type { WebSocket } from 'ws'
 
-import type { ChannelContext, Context } from '../context/index.js'
+import type {
+  ChannelContext,
+  ConnectContext,
+  Context
+} from '../context/index.js'
 import type { ServerClient } from '../server-client/index.js'
 
+interface LogFn {
+  (...objs: unknown[]): void
+}
+
 interface TypeOptions {
   /**
    * Name of the queue that will be used to process actions
@@ -40,6 +48,23 @@ interface ChannelOptions {
   queue?: string
 }
 
+interface ConnectLoader<Headers extends object = unknown> {
+  (
+    ctx: ConnectContext<Headers>,
+    lastSynced: number
+  ):
+    | [Action, ServerMeta][]
+    | Promise<
+        [
+          Action,
+          Partial<Pick<ServerMeta, 'added' | 'subprotocol'>> &
+            Pick<ServerMeta, 'id' | 'time'>
+        ][]
+      >
+}
+
+type ServerNodeConstructor = new (...args: unknown[]) => ServerNode
+
 export interface ServerMeta extends Meta {
   /**
    * All nodes subscribed to channel will receive the action.
@@ -98,12 +123,6 @@ export interface ServerMeta extends Meta {
 }
 
 export interface BaseServerOptions {
-  /**
-   * URL to PHP, Ruby on Rails, or other backend to process actions and
-   * authentication.
-   */
-  backend?: string
-
   /**
    * SSL certificate or path to it. Path could be relative from server
    * root. It is required in production mode, because WSS is highly
@@ -119,17 +138,7 @@ export interface BaseServerOptions {
   cleanFromLog?: RegExp
 
   /**
-   * CIDR masks for IP address, where control requests could came from.
-   */
-  controlMask?: string
-
-  /**
-   * Secret to control the server.
-   */
-  controlSecret?: string
-
-  /**
-   * Disable health check endpoint, control HTTP API, {@link Server#http}.
+   * Disable health check endpoint, {@link Server#http}.
    *
    * The server will process only WebSocket connection and ignore all other
    * HTTP request (so they can be processed by other HTTP server).
@@ -144,8 +153,8 @@ export interface BaseServerOptions {
   env?: 'development' | 'production'
 
   /**
-   * URL of main JS file in the root dir. Shortcut to set `root` in ES modules
-   * without `fileURLToPath`.
+   * URL of main JS file in the root dir for the cases where you can’t use
+   * `import.meta.dirname`.
    *
    * ```
    * fileUrl: import.meta.url
@@ -169,6 +178,16 @@ export interface BaseServerOptions {
    */
   key?: { pem: string } | string
 
+  /**
+   * The version requirements for client subprotocol version.
+   */
+  minSubprotocol?: number
+
+  /**
+   * Replace class for ServerNode.
+   */
+  Node?: ServerNodeConstructor
+
   /**
    * Process ID, to display in logs.
    */
@@ -184,7 +203,7 @@ export interface BaseServerOptions {
    * Port to bind server. It will create HTTP server manually to connect
    * WebSocket server to it. Default is `31337`.
    */
-  port?: number
+  port?: number | string
 
   /**
    * URL to Redis for Logux Server Pro scaling.
@@ -196,7 +215,7 @@ export interface BaseServerOptions {
    * Default is `process.cwd()`.
    *
    * ```js
-   * root: __dirname
+   * root: import.meta.dirname
    * ```
    */
   root?: string
@@ -215,14 +234,17 @@ export interface BaseServerOptions {
   store?: LogStore
 
   /**
-   * Server current application subprotocol version in SemVer format.
+   * Server current application subprotocol version.
    */
-  subprotocol?: string
+  subprotocol?: number
 
   /**
-   * npm’s version requirements for client subprotocol version.
+   * How many actions could be sent in a single message. `100` by default.
+   *
+   * Actions from a single `Server#log.add()` call (or from `ctx.sendBack()`
+   * with an array) are sent together and will be split by this limit.
    */
-  supports?: string
+  syncBatch?: number
 
   /**
    * Test time to test server.
@@ -236,8 +258,11 @@ export interface BaseServerOptions {
   timeout?: number
 }
 
-export interface AuthenticatorOptions<Headers extends object> {
-  client: ServerClient
+export interface AuthenticatorOptions<
+  Headers extends object,
+  ClientData extends object
+> {
+  client: ServerClient<ClientData>
   cookie: Record<string, string>
   headers: Headers
   token: string
@@ -245,9 +270,8 @@ export interface AuthenticatorOptions<Headers extends object> {
 }
 
 export type SendBackActions =
-  | [Action, Partial<Meta>][]
+  | (Action | [Action, Partial<Meta>])[]
   | Action
-  | Action[]
   | void
 
 /**
@@ -258,8 +282,11 @@ export type SendBackActions =
  * @param client Client object.
  * @returns `true` if credentials was correct
  */
-interface ServerAuthenticator<Headers extends object> {
-  (user: AuthenticatorOptions<Headers>): boolean | Promise<boolean>
+interface ServerAuthenticator<
+  Headers extends object,
+  ClientData extends object
+> {
+  (user: AuthenticatorOptions<Headers, ClientData>): boolean | Promise<boolean>
 }
 
 /**
@@ -352,7 +379,7 @@ interface ActionFinally<
  */
 interface ChannelFilter<Headers extends object> {
   (
-    ctx: Context<{}, Headers>,
+    ctx: Context<unknown, Headers>,
     action: Readonly<Action>,
     meta: Readonly<ServerMeta>
   ): boolean | Promise<boolean>
@@ -466,10 +493,7 @@ type ActionCallbacks<
   TypeAction extends Action,
   Data extends object,
   Headers extends object
-> = {
-  finally?: ActionFinally<TypeAction, Data, Headers>
-  resend?: Resender<TypeAction, Data, Headers>
-} & (
+> = (
   | {
       access: Authorizer<TypeAction, Data, Headers>
       process?: Processor<TypeAction, Data, Headers>
@@ -477,18 +501,17 @@ type ActionCallbacks<
   | {
       accessAndProcess: Processor<TypeAction, Data, Headers>
     }
-)
+) & {
+  finally?: ActionFinally<TypeAction, Data, Headers>
+  resend?: Resender<TypeAction, Data, Headers>
+}
 
 type ChannelCallbacks<
   SubscribeAction extends Action,
   Data extends object,
   ChannelParams extends object | string[],
   Headers extends object
-> = {
-  filter?: FilterCreator<SubscribeAction, Data, ChannelParams, Headers>
-  finally?: ChannelFinally<SubscribeAction, Data, ChannelParams, Headers>
-  unsubscribe?: ChannelUnsubscribe<Data, ChannelParams, Headers>
-} & (
+> = (
   | {
       access: ChannelAuthorizer<SubscribeAction, Data, ChannelParams, Headers>
       load?: ChannelLoader<SubscribeAction, Data, ChannelParams, Headers>
@@ -501,7 +524,11 @@ type ChannelCallbacks<
         Headers
       >
     }
-)
+) & {
+  filter?: FilterCreator<SubscribeAction, Data, ChannelParams, Headers>
+  finally?: ChannelFinally<SubscribeAction, Data, ChannelParams, Headers>
+  unsubscribe?: ChannelUnsubscribe<Data, ChannelParams, Headers>
+}
 
 interface ActionReporter {
   action: Readonly<Action>
@@ -551,20 +578,17 @@ interface ReportersArguments {
     nodeId?: string
   }
   listen: {
-    backend: string
     cert: boolean
-    controlMask: string
-    controlSecret: string
     environment: 'development' | 'production'
     host: string
     loguxServer: string
+    minSubprotocol: number
     nodeId: string
     notes: object
     port: string
     redis: string
     server: boolean
-    subprotocol: string
-    supports: string
+    subprotocol: number
   }
   processed: {
     actionId: ID
@@ -607,29 +631,13 @@ export type Resend =
   | string[]
 
 export interface Logger {
+  debug(details: object, message: string): void
   error(details: object, message: string): void
   fatal(details: object, message: string): void
   info(details: object, message: string): void
   warn(details: object, message: string): void
 }
 
-interface Response {
-  body: string
-  header?: {
-    [name: string]: string
-  }
-}
-
-interface GetProcessor {
-  request(request: object): Promise<Response> | Response
-  safe?: boolean
-}
-
-interface PostProcessor {
-  command(command: object, request: object): Promise<void>
-  isValid(command: object): boolean
-}
-
 /**
  * Return `false` if `cb()` got response error with 403.
  *
@@ -651,8 +659,9 @@ export function wasNot403(cb: () => Promise<void>): Promise<boolean>
  * Base server class to extend.
  */
 export class BaseServer<
-  Headers extends object = {},
-  ServerLog extends Log = Log<ServerMeta>
+  Headers extends object = unknown,
+  ServerLog extends Log = Log<ServerMeta>,
+  ClientData extends object = unknown
 > {
   /**
    * Connected client by client ID.
@@ -660,7 +669,7 @@ export class BaseServer<
    * Do not rely on this data, when you have multiple Logux servers.
    * Each server will have a different list.
    */
-  clientIds: Map<string, ServerClient>
+  clientIds: Map<string, ServerClient<ClientData>>
 
   /**
    * Connected clients.
@@ -671,14 +680,7 @@ export class BaseServer<
    * }
    * ```
    */
-  connected: Map<string, ServerClient>
-
-  /**
-   * Add callback to internal HTTP server.
-   */
-  controls: {
-    [path: string]: GetProcessor | PostProcessor
-  }
+  connected: Map<string, ServerClient<ClientData>>
 
   /**
    * Production or development mode.
@@ -735,7 +737,7 @@ export class BaseServer<
    * Do not rely on this data, when you have multiple Logux servers.
    * Each server will have a different list.
    */
-  nodeIds: Map<string, ServerClient>
+  nodeIds: Map<string, ServerClient<ClientData>>
 
   /**
    * Server options.
@@ -755,7 +757,7 @@ export class BaseServer<
   subscribers: {
     [channel: string]: {
       [nodeId: string]: {
-        filters: Record<string, ChannelFilter<{}> | true>
+        filters: Record<string, ChannelFilter<unknown> | true>
         unsubscribe?: (action: LoguxUnsubscribeAction, meta: ServerMeta) => void
       }
     }
@@ -767,7 +769,7 @@ export class BaseServer<
    * Do not rely on this data, when you have multiple Logux servers.
    * Each server will have a different list.
    */
-  userIds: Map<string, ServerClient[]>
+  userIds: Map<string, ServerClient<ClientData>[]>
 
   /**
    * @param opts Server options.
@@ -800,7 +802,7 @@ export class BaseServer<
    *
    * @param authenticator The authentication callback.
    */
-  auth(authenticator: ServerAuthenticator<Headers>): void
+  auth(authenticator: ServerAuthenticator<Headers, ClientData>): void
 
   /**
    * Define the channel.
@@ -827,15 +829,14 @@ export class BaseServer<
    * @param options Additional options
    */
   channel<
-    ChannelParams extends object = {},
-    Data extends object = {},
+    ChannelParams extends object = unknown,
+    Data extends object = unknown,
     SubscribeAction extends LoguxSubscribeAction = LoguxSubscribeAction
   >(
     pattern: string,
     callbacks: ChannelCallbacks<SubscribeAction, Data, ChannelParams, Headers>,
     options?: ChannelOptions
   ): void
-
   /**
    * @param pattern Regular expression for channel name.
    * @param callbacks Callback during subscription process.
@@ -843,7 +844,7 @@ export class BaseServer<
    */
   channel<
     ChannelParams extends string[] = string[],
-    Data extends object = {},
+    Data extends object = unknown,
     SubscribeAction extends LoguxSubscribeAction = LoguxSubscribeAction
   >(
     pattern: RegExp,
@@ -877,25 +878,68 @@ export class BaseServer<
    */
   destroy(): Promise<void>
 
+  /**
+   * Wait until the client will confirm all actions, which were sent to it.
+   *
+   * Use it to send a long history without loading it all into the memory:
+   * the client’s speed will limit how fast you read the database.
+   *
+   * ```js
+   * while (await server.drain(clientId)) {
+   *   let page = await cursor.next(100)
+   *   if (!page.length) break
+   *   server.log.add(page.map(i => [i.action, { clients: [clientId] }]))
+   * }
+   * ```
+   *
+   * @param clientId Client ID.
+   * @returns Promise with `false` if the client was disconnected.
+   */
+  drain(clientId: string): Promise<boolean>
+
+  /**
+   * Handle WebSocket connection explicitly
+   *
+   * This is a low-level method allowing to integrate Logux server with an existing server
+   *
+   * ```js
+   * fastify.get('/', { websocket: true }, (socket, req) => {
+   *   loguxServer.handleClient(socket, req)
+   * })
+   * ```
+   */
+  handleClient(ws: WebSocket, req: IncomingMessage): void
+
   /**
    * Add non-WebSocket HTTP request processor.
    *
    * ```js
-   * server.http((req, res) => {
-   *   if (req.url === '/auth') {
-   *     let token = signIn(req)
-   *     if (token) {
-   *       res.setHeader('Set-Cookie', `token=${token}; Secure; HttpOnly`)
-   *       res.end()
-   *     } else {
-   *       res.statusCode = 400
-   *       res.end('Wrong user or password')
-   *     }
+   * server.http('GET', '/auth', (req, res) => {
+   *   let token = signIn(req)
+   *   if (token) {
+   *     res.setHeader('Set-Cookie', `token=${token}; Secure; HttpOnly`)
+   *     res.end()
+   *   } else {
+   *     res.statusCode = 400
+   *     res.end('Wrong user or password')
    *   }
    * })
    * ```
    */
-  http(listener: (req: IncomingMessage, res: ServerResponse) => void): void
+  http(
+    method: string,
+    url: string,
+    listener: (
+      req: IncomingMessage,
+      res: ServerResponse
+    ) => Promise<void> | void
+  ): void
+  http(
+    listener: (
+      req: IncomingMessage,
+      res: ServerResponse
+    ) => boolean | Promise<boolean>
+  ): void
 
   /**
    * Start WebSocket server and listen for clients.
@@ -909,7 +953,6 @@ export class BaseServer<
    * @param listener Event listener.
    */
   on(event: 'subscriptionCancelled', listener: () => void): Unsubscribe
-
   /**
    * @param event The event name.
    * @param listener Subscription listener.
@@ -918,38 +961,34 @@ export class BaseServer<
     event: 'subscribing',
     listener: (action: LoguxSubscribeAction, meta: Readonly<ServerMeta>) => void
   ): Unsubscribe
-
   /**
    * @param event The event name.
    * @param listener Processing listener.
    */
   on(
-    event: 'backendGranted' | 'backendProcessed' | 'processed',
+    event: 'processed',
     listener: (
       action: Action,
       meta: Readonly<ServerMeta>,
       latencyMilliseconds: number
     ) => void
   ): Unsubscribe
-
   /**
    * @param event The event name.
    * @param listener Action listener.
    */
   on(
-    event: 'add' | 'backendSent' | 'clean',
+    event: 'add' | 'clean',
     listener: (action: Action, meta: Readonly<ServerMeta>) => void
   ): Unsubscribe
-
   /**
    * @param event The event name.
    * @param listener Client listener.
    */
   on(
     event: 'connected' | 'disconnected',
-    listener: (client: ServerClient) => void
+    listener: (client: ServerClient<ClientData>) => void
   ): Unsubscribe
-
   /**
    * Subscribe for synchronization events. It implements nanoevents API.
    * Supported events:
@@ -985,7 +1024,6 @@ export class BaseServer<
     event: 'clientError' | 'fatal',
     listener: (err: Error) => void
   ): Unsubscribe
-
   /**
    * @param event The event name.
    * @param listener Error listener.
@@ -994,16 +1032,17 @@ export class BaseServer<
     event: 'error',
     listener: (err: Error, action: Action, meta: Readonly<ServerMeta>) => void
   ): Unsubscribe
-
   /**
    * @param event The event name.
    * @param listener Client listener.
    */
   on(
     event: 'authenticated' | 'unauthenticated',
-    listener: (client: ServerClient, latencyMilliseconds: number) => void
+    listener: (
+      client: ServerClient<ClientData>,
+      latencyMilliseconds: number
+    ) => void
   ): Unsubscribe
-
   /**
    * @param event The event name.
    * @param listener Action listener.
@@ -1012,7 +1051,6 @@ export class BaseServer<
     event: 'preadd',
     listener: (action: Action, meta: ServerMeta) => void
   ): Unsubscribe
-
   /**
    * @param event The event name.
    * @param listener Subscription listener.
@@ -1025,7 +1063,6 @@ export class BaseServer<
       latencyMilliseconds: number
     ) => void
   ): Unsubscribe
-
   /**
    * @param event The event name.
    * @param listener Subscription listener.
@@ -1038,7 +1075,6 @@ export class BaseServer<
       clientNodeId: string
     ) => void
   ): Unsubscribe
-
   /**
    * @param event The event name.
    * @param listener Report listener.
@@ -1064,7 +1100,7 @@ export class BaseServer<
    *
    * @param callbacks Callback during subscription process.
    */
-  otherChannel<Data extends object = {}>(
+  otherChannel<Data extends object = unknown>(
     callbacks: ChannelCallbacks<LoguxSubscribeAction, Data, [string], Headers>
   ): void
 
@@ -1094,7 +1130,7 @@ export class BaseServer<
    *
    * @param callbacks Callbacks for actions with this type.
    */
-  otherType<Data extends object = {}>(
+  otherType<Data extends object = unknown>(
     callbacks: ActionCallbacks<Action, Data, Headers>
   ): void
 
@@ -1106,8 +1142,8 @@ export class BaseServer<
    * @param meta Action’s meta.
    * @returns Promise until new action will be resend to clients and processed.
    */
-  process(
-    action: AnyAction,
+  process<TypeAction extends Action = AnyAction>(
+    action: TypeAction,
     meta?: Partial<ServerMeta>
   ): Promise<Readonly<ServerMeta>>
 
@@ -1131,6 +1167,27 @@ export class BaseServer<
    */
   sendAction(action: Action, meta: ServerMeta): Promise<void> | void
 
+  /**
+   * Change a way how server loads actions history for the client.
+   *
+   * ```js
+   * server.sendOnConnect(async (ctx, lastSynced) => {
+   *   return db.loadActions({ user: ctx.userId, after: lastSynced })
+   * })
+   * ```
+   *
+   * Actions should be returned from the newest one to the oldest one.
+   * The list will be split into messages by the `syncBatch` option, but it
+   * is loaded into the memory as a whole. For a big history send it by
+   * pages with `Context#sendBack()` and `Context#drain()` instead.
+   *
+   * Set `meta.added` to let the client ask only for newer actions after
+   * the reconnect: the biggest `added` will be sent as the sync position.
+   *
+   * @param loader Callback which loads list of actions and meta.
+   */
+  sendOnConnect(loader: ConnectLoader<Headers>): void
+
   /**
    * Send `logux/subscribed` if client was not already subscribed.
    *
@@ -1148,12 +1205,11 @@ export class BaseServer<
    * @param callbacks Callbacks for action created by creator.
    * @param options Additional options
    */
-  type<Creator extends AbstractActionCreator, Data extends object = {}>(
+  type<Creator extends AbstractActionCreator, Data extends object = unknown>(
     actionCreator: Creator,
     callbacks: ActionCallbacks<ReturnType<Creator>, Data, Headers>,
     options?: TypeOptions
   ): void
-
   /**
    * Define action type’s callbacks.
    *
@@ -1177,7 +1233,7 @@ export class BaseServer<
    * @param callbacks Callbacks for actions with this type.
    * @param options Additional options
    */
-  type<TypeAction extends Action = AnyAction, Data extends object = {}>(
+  type<TypeAction extends Action = AnyAction, Data extends object = unknown>(
     name: RegExp | TypeAction['type'],
     callbacks: ActionCallbacks<TypeAction, Data, Headers>,
     options?: TypeOptions