@seriousme/opifex 1.11.2 → 2.0.3

package/dist/server/context.d.ts

@@ -1,47 +1,221 @@
-import { MqttConn } from "./deps.ts";
-import type { AnyPacket, IPersistence, IStore, ProtocolLevel, PublishPacket, SockConn, TAuthenticationResult, Timer, Topic } from "./deps.ts";
+import { MqttConn, OutboundTopicAliasManager, Timer } from "./deps.ts";
+import type { AnyPacket, ConnectPacket, ExtPublishPacket, IPersistence, PacketId, ProtocolLevel, ShareName, SockConn, Topic, TReasonCode } from "./deps.ts";
+import type { Configuration } from "./config.ts";
+/** Unique identifier for an MQTT client. */
 export type ClientId = string;
+/** System topic prefix character used for internal MQTT system topics. */
 export declare const SysPrefix = "$";
+/** Standard UTF-8 encoder used across the server to convert strings to byte arrays. */
 export declare const utf8Encoder: TextEncoder;
+/** Possible results from isAuthenticated and processAuth handler */
+export type AuthenticatedResult = {
+    reasonCode: TReasonCode;
+    reasonString?: string;
+    authData?: Uint8Array;
+};
+export declare const SessionState: {
+    readonly connecting: 0;
+    readonly authenticating: 1;
+    readonly connected: 2;
+    readonly closing: 3;
+    readonly disconnected: 4;
+};
+export type SessionState = typeof SessionState[keyof typeof SessionState];
 /**
  * Handlers are hooks that the server will call
  * and let you influence the servers behaviour.
  * The following handlers can be configured:
- *  - isAuthenticated()
- *  - isAuthorizedToPublish()
- *  - isAuthorizedToSubscribe()
+ * - preconnect()
+ * - isAuthenticated()
+ * - processAuth()
+ * - isAuthorizedToPublish()
+ * - isAuthorizedToSubscribe()
  */
 export type Handlers = {
-    isAuthenticated?(ctx: Context, clientId: ClientId, username: string, password: Uint8Array): TAuthenticationResult;
-    isAuthorizedToPublish?(ctx: Context, topic: Topic): boolean;
-    isAuthorizedToSubscribe?(ctx: Context, topic: Topic): boolean;
+    /**
+     * Default preconnect handler that unconditionally permits all connections.
+     * @param {SockConn} conn - The connection context.
+     * @returns {boolean} false will close the connection
+     */
+    preconnect?(conn: SockConn): boolean | Promise<boolean>;
+    /**
+     * Hook to authenticate a client connection attempt.
+     * @param {Context} ctx - The connection context.
+     * @param {ClientId} clientId - The client identifier.
+     * @param {string} username - The username provided by the client.
+     * @param {Uint8Array} password - The password bytes provided by the client.
+     * @param {ConnectPacket} connectPacket - The raw connect packet
+     * @returns {AuthResult} The result of the authentication attempt.
+     */
+    isAuthenticated?(ctx: Context, clientId: ClientId, username: string, password: Uint8Array, connectPacket: ConnectPacket): AuthenticatedResult | Promise<AuthenticatedResult>;
+    /**
+     * Hook to authenticate a client connection attempt.
+     * @param {Context} ctx - The connection context.
+     * @param {ClientId} clientId - The client identifier.
+     * @param {string} authMethod - The authentication method provided by the client.
+     * @param {Uint8Array} authData- The authentication data provided by the client.
+     * @returns {AuthenticationResult} The result of the authentication attempt.
+     */
+    processAuth?(ctx: Context, clientId: ClientId, authMethod: string, authData: Uint8Array): AuthenticatedResult | Promise<AuthenticatedResult>;
+    /**
+     * Hook to authorize a message publication to a specific topic.
+     * @param {Context} ctx - The connection context.
+     * @param {Topic} topic - The topic the client wants to publish to.
+     * @returns {boolean} True if the client is authorized to publish, false otherwise.
+     */
+    isAuthorizedToPublish?(ctx: Context, topic: Topic): boolean | Promise<boolean>;
+    /**
+     * Hook to authorize a subscription request to a specific topic.
+     * @param {Context} ctx - The connection context.
+     * @param {Topic} topic - The topic filter the client wants to subscribe to.
+     * @param {ShareName} shareName - The name of the share in case of shared subscriptions
+     * @returns {boolean} True if the client is authorized to subscribe, false otherwise.
+     */
+    isAuthorizedToSubscribe?(ctx: Context, topic: Topic, shareName: ShareName): boolean | Promise<boolean>;
+};
+/**
+ * V5 options that can be passed by handleConnect
+ */
+export type ConnectOptions = {
+    sessionExpiryInterval?: number | undefined;
+    willDelayInterval?: number | undefined;
+    topicAliasMaximum?: number | undefined;
+    maximumOutgoingPacketSize?: number | undefined;
+    receiveMaximum?: number | undefined;
+    assignedClientIdentifier?: string | undefined;
+    keepAlive?: number | undefined;
 };
 /**
- * The Context class is used to maintain state of a MQTT connection
- * It handles:
- *  - connect/disconnect including broadcasting of these events
- *  - publish
- *  - persistence
- *  - the will
+ * Per-connection server context that manages the lifecycle, packets,
+ * timers, and persistence interactions for an individual client connection.
  */
 export declare class Context {
-    connected: boolean;
+    /** the client id is set after succesful connect */
+    clientId: ClientId | null;
+    /** Indicates the current state of the client  */
+    state: SessionState;
+    /** Indicates whether the client asked for a clean session */
+    cleanSession: boolean;
+    /** Indicates whether the client is considered a broker and allowed  to use $SYS topics etc */
+    isBroker: boolean;
+    /** The MQTT protocol level version determined during the connection handshake. */
     protocolLevel: ProtocolLevel;
+    /** The underlying raw socket connection. */
     conn: SockConn;
+    /** The wrapped MQTT connection wrapper handling frame reading and writing. */
     mqttConn: MqttConn;
+    /** The persistence layer instance used by the server. */
     persistence: IPersistence;
+    /** The configured authentication and authorization lifecycle hooks. */
     handlers: Handlers;
+    /** Configuration data */
+    config: Configuration;
+    /** Global registry mapping active client identifiers to their respective connection context. */
     static clientList: Map<ClientId, Context>;
-    store?: IStore;
-    will?: PublishPacket;
+    /** The optional Will packet configured by the client to be published if disconnected unexpectedly. */
+    will?: ExtPublishPacket | undefined;
+    /** The Keep Alive timer tracking the client activity timeout. */
     timer?: Timer;
-    constructor(persistence: IPersistence, conn: SockConn, handlers: Handlers);
-    send(packet: AnyPacket): Promise<void>;
-    connect(clientId: string, clean: boolean): void;
-    doPublish(packet: PublishPacket): void;
-    clean(clientId: string): void;
-    close(executewill?: boolean): void;
+    /** Timer to keep track of when a V5 session ends */
+    sessionEndsTimer?: Timer;
+    /** Timer to handle V5 delayed will delivery */
+    willTimer?: Timer;
+    /**
+     * Timer enforcing a deadline for the client to send a CONNECT packet
+     * after establishing a socket connection.
+     */
+    preconnectTimer?: Timer;
+    /**
+     *  max number of inflight packets for this client,
+     *  in V5 client can set this lower than maxInflightMessages
+     *  theoretical max is maxInt
+     */
+    receiveMaximum: number;
+    /**
+     * inflighPackets, how many publish packets have been sent and are waiting for ack
+     */
+    inflightPackets: number;
+    /**
+     * set of Id's of publish packets waiting to be send to the client
+     */
+    queuedPacketIds: Set<PacketId>;
+    /**
+     * V5,max topicAliases ,0 = none
+     */
+    outgoingMaxTopicAlias: number;
+    incomingMaxTopicAlias: number;
+    /** V5 server topic aliases */
+    incomingTopicAliases: Map<number, Topic>;
+    /** V5 client topic aliases */
+    outgoingTopicAliasManager: undefined | OutboundTopicAliasManager;
+    connectOptions: undefined | ConnectOptions;
+    /**
+     * Initializes a new instance of the connection Context.
+     */
+    constructor(configuration: Configuration, // all settings
+    persistence: IPersistence, // The server persistence layer implementation.
+    conn: SockConn, // The underlying socket connection.
+    handlers: Handlers);
+    /**
+     * Configures and starts the preconnect timer to enforce connection deadlines.
+     */
+    private initializePreconnectTimer;
+    /**
+     * Transmits an MQTT packet to the client.
+     */
+    send(packet: AnyPacket): Promise<boolean>;
+    /**
+     * Dispatch the next publish packet in queue (if exists),
+     * when a ack packet on an already sent publish arrives
+     */
+    processAck(packetId: PacketId): Promise<boolean>;
+    /**
+     * Dispatch publish packets to client
+     */
+    dispatch(extPacket: ExtPublishPacket): Promise<void>;
+    /**
+     * Helper to setup the timers
+     */
+    private setupConnectionTimers;
+    /**
+     * process V5 connectOptions
+     */
+    private applyConnectOptions;
+    /**
+     * Finalizes the client connection state, registers the client in persistence,
+     * kicks out existing duplicate sessions, and broadcasts the client connection event.
+     */
+    prepareConnect(packet: ConnectPacket, clientId: string, connectOpts?: ConnectOptions): void;
+    connect(): Promise<boolean>;
+    /**
+     * Proces -inbound- publication requests
+     */
+    publish(packet: ExtPublishPacket): Promise<void>;
+    /**
+     * Explicitly removes a client session and its stored state from the persistence layer.
+     */
+    clean(): Promise<void>;
+    /**
+     * Tears down the connection context, terminates the underlying socket,
+     * clears internal timers, triggers the Will packet execution if requested,
+     * and announces the client disconnection.
+     * If executewill=true triggers the registered Will packet logic.
+     */
+    close(executewill?: boolean): Promise<void>;
+    /**
+     * Evaluates authorization and triggers the distribution of the client's Will packet.
+     */
     private handleWill;
-    broadcast(topic: Topic, payload: string, retain?: boolean): void;
+    /**
+     * Utility method to generate and publish an internal system message payload to the persistence engine.
+     */
+    broadcast(topic: Topic, // The topic filter string to publish to.
+    payload: string, // The plain-text message string to encode.
+    retain?: boolean): Promise<void>;
+    /**
+     * utility method to redeliver packets that were cached
+     * called from handleConnect()
+     */
+    handleRedelivery(): Promise<void>;
 }
 //# sourceMappingURL=context.d.ts.map

package/dist/server/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../server/context.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,QAAQ,EAIT,MAAM,WAAW,CAAC;AACnB,OAAO,KAAK,EACV,SAAS,EACT,YAAY,EACZ,MAAM,EACN,aAAa,EACb,aAAa,EACb,QAAQ,EACR,qBAAqB,EACrB,KAAK,EACL,KAAK,EACN,MAAM,WAAW,CAAC;AAEnB,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC;AAE9B,eAAO,MAAM,SAAS,MAAM,CAAC;AAE7B,eAAO,MAAM,WAAW,aAAoB,CAAC;AAE7C;;;;;;;GAOG;AACH,MAAM,MAAM,QAAQ,GAAG;IACrB,eAAe,CAAC,CACd,GAAG,EAAE,OAAO,EACZ,QAAQ,EAAE,QAAQ,EAClB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,UAAU,GACnB,qBAAqB,CAAC;IACzB,qBAAqB,CAAC,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC;IAC5D,uBAAuB,CAAC,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC;CAC/D,CAAC;AAEF;;;;;;;GAOG;AAEH,qBAAa,OAAO;IAClB,SAAS,EAAE,OAAO,CAAC;IACnB,aAAa,EAAE,aAAa,CAAC;IAC7B,IAAI,EAAE,QAAQ,CAAC;IACf,QAAQ,EAAE,QAAQ,CAAC;IACnB,WAAW,EAAE,YAAY,CAAC;IAC1B,QAAQ,EAAE,QAAQ,CAAC;IACnB,MAAM,CAAC,UAAU,EAAE,GAAG,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAa;IACtD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,aAAa,CAAC;IACrB,KAAK,CAAC,EAAE,KAAK,CAAC;gBAEF,WAAW,EAAE,YAAY,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ;IASnE,IAAI,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAM5C,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI;IAiB/C,SAAS,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI;IActC,KAAK,CAAC,QAAQ,EAAE,MAAM;IAItB,KAAK,CAAC,WAAW,UAAO,GAAG,IAAI;IA6B/B,OAAO,CAAC,UAAU;IAYlB,SAAS,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,UAAQ,GAAG,IAAI;CAa/D"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../server/context.ts"],"names":[],"mappings":"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"}