@mtcute/core 0.16.7 → 0.16.9

package/network/network-manager.d.ts

@@ -0,0 +1,248 @@
+import { mtp, tl } from '@mtcute/tl';
+import { TlReaderMap, TlWriterMap } from '@mtcute/tl-runtime';
+import { default as Long } from 'long';
+import { StorageManager } from '../storage/storage.js';
+import { Middleware } from '../utils/composer.js';
+import { DcOptions, ICryptoProvider, Logger } from '../utils/index.js';
+import { ConfigManager } from './config-manager.js';
+import { MultiSessionConnection } from './multi-session-connection.js';
+import { PersistentConnectionParams } from './persistent-connection.js';
+import { ReconnectionStrategy } from './reconnection.js';
+import { SessionConnection } from './session-connection.js';
+import { TransportFactory } from './transports/index.js';
+export type ConnectionKind = 'main' | 'upload' | 'download' | 'downloadSmall';
+/**
+ * Params passed into {@link NetworkManager} by {@link TelegramClient}.
+ * This type is intended for internal usage only.
+ */
+export interface NetworkManagerParams {
+    storage: StorageManager;
+    crypto: ICryptoProvider;
+    log: Logger;
+    enableErrorReporting: boolean;
+    apiId: number;
+    initConnectionOptions?: Partial<Omit<tl.RawInitConnectionRequest, 'apiId' | 'query'>>;
+    transport: TransportFactory;
+    reconnectionStrategy?: ReconnectionStrategy<PersistentConnectionParams>;
+    disableUpdates?: boolean;
+    testMode: boolean;
+    layer: number;
+    useIpv6: boolean;
+    readerMap: TlReaderMap;
+    writerMap: TlWriterMap;
+    isPremium: boolean;
+    emitError: (err: Error, connection?: SessionConnection) => void;
+    onUpdate: (upd: tl.TypeUpdates) => void;
+    onUsable: () => void;
+    onConnecting: () => void;
+    onNetworkChanged: (connected: boolean) => void;
+    stopSignal: AbortSignal;
+}
+export type ConnectionCountDelegate = (kind: ConnectionKind, dcId: number, isPremium: boolean) => number;
+/**
+ * Additional params passed into {@link NetworkManager} by the user
+ * that customize the behavior of the manager
+ */
+export interface NetworkManagerExtraParams {
+    /**
+     * Whether to use PFS (Perfect Forward Secrecy) for all connections.
+     * This is disabled by default
+     */
+    usePfs?: boolean;
+    /**
+     * Connection count for each connection kind.
+     * The function should be pure to avoid unexpected behavior.
+     *
+     * Defaults to TDLib logic:
+     *   - main: 0 (which stands for "handle internally, based on tmp_sessions value")
+     *   - upload: if premium or dc id is other than 2 or 4, then 8, otherwise 4
+     *   - download: if premium then 8, otherwise 2
+     *   - downloadSmall: 2
+     *
+     * Non-zero value for `main` is **for advanced users only**
+     * as it may lead to unexpected behavior, and is generally not recommended
+     * because of unnecessary extra load on both the server and the client as well as
+     * increased possibility of encountering AUTH_KEY_DUPLICATED errors.
+     */
+    connectionCount?: ConnectionCountDelegate;
+    /**
+     * Idle timeout for non-main connections, in ms
+     *
+     * @default  60000 (60 seconds).
+     */
+    inactivityTimeout?: number;
+    /**
+     * List of middlewares to use for the network manager
+     *
+     * > **Note**: these middlewares apply to **outgoing requests only**.
+     * > If you need to handle incoming updates, use a {@link Dispatcher} instead.
+     */
+    middlewares?: Middleware<RpcCallMiddlewareContext, unknown>[];
+}
+/** Options that can be customized when making an RPC call */
+export interface RpcCallOptions {
+    /**
+     * If the call results in a `FLOOD_WAIT_X` error,
+     * the maximum amount of time to wait before retrying.
+     *
+     * If set to `0`, the call will not be retried.
+     *
+     * Only applies when the flood waiter middleware is enabled.
+     */
+    floodSleepThreshold?: number;
+    /**
+     * If the call results in an internal server error or a flood wait,
+     * the maximum amount of times to retry the call.
+     *
+     * Only applies when the flood waiter middleware and/or
+     * internal errors handler middleware is enabled.
+     */
+    maxRetryCount?: number;
+    /**
+     * Timeout for the call, in milliseconds.
+     *
+     * @default Infinity
+     */
+    timeout?: number;
+    /**
+     * **ADVANCED**
+     *
+     * Kind of connection to use for this call.
+     *
+     * @default 'main'
+     */
+    kind?: ConnectionKind;
+    /**
+     * **ADVANCED**
+     *
+     * ID of the DC to use for this call
+     */
+    dcId?: number;
+    /**
+     * **ADVANCED**
+     *
+     * DC connection manager to use for this call.
+     * Overrides `dcId` if set.
+     */
+    manager?: DcConnectionManager;
+    /**
+     * Abort signal for the call.
+     */
+    abortSignal?: AbortSignal;
+    /**
+     * Whether we should not retry on -503 errors and throw {@link MtTimeoutError} immediately instead.
+     *
+     * Useful for methods like `messages.getBotCallbackAnswer` that reliably return
+     * -503 in case the upstream bot failed to respond.
+     *
+     * Only applies if the internal error handler middleware is enabled,
+     * otherwise -503 is always thrown.
+     */
+    throw503?: boolean;
+    /**
+     * Whether the `X_MIGRATE_%d` errors should be handled locally on request level
+     * instead of changing the default datacenter for the entire client.
+     *
+     * Useful for `invokeWithBusinessConnection`, as it returns a `USER_MIGRATE_%d` error
+     * that is in fact not related to the user, but to the specific request.
+     */
+    localMigrate?: boolean;
+    /**
+     * Some requests should be processed consecutively, and not in parallel.
+     * Using the same `chainId` for multiple requests will ensure that they are processed in the order
+     * of calling `.call()`.
+     *
+     * Particularly useful for `messages.sendMessage` and alike.
+     */
+    chainId?: string | number;
+}
+export interface RpcCallMiddlewareContext {
+    request: tl.RpcMethod;
+    manager: NetworkManager;
+    params?: RpcCallOptions;
+}
+export type RpcCallMiddleware<Result = unknown> = Middleware<RpcCallMiddlewareContext, Result>;
+/**
+ * Wrapper over all connection pools for a single DC.
+ */
+export declare class DcConnectionManager {
+    /** Network manager instance */
+    readonly manager: NetworkManager;
+    /** DC ID */
+    readonly dcId: number;
+    /** DC options to use */
+    readonly _dcs: DcOptions;
+    /** Whether this DC is the primary one */
+    isPrimary: boolean;
+    private _salts;
+    private _log;
+    /** Main connection pool */
+    main: MultiSessionConnection;
+    /** Upload connection pool */
+    upload: MultiSessionConnection;
+    /** Download connection pool */
+    download: MultiSessionConnection;
+    /** Download connection pool (for small files) */
+    downloadSmall: MultiSessionConnection;
+    private get _mainCountOverride();
+    constructor(
+    /** Network manager instance */
+    manager: NetworkManager, 
+    /** DC ID */
+    dcId: number, 
+    /** DC options to use */
+    _dcs: DcOptions, 
+    /** Whether this DC is the primary one */
+    isPrimary?: boolean);
+    private _setupMulti;
+    setIsPrimary(isPrimary: boolean): void;
+    setIsPremium(isPremium: boolean): void;
+    loadKeys(forcePfs?: boolean): Promise<boolean>;
+    setMainConnectionCount(count: number): void;
+    destroy(): Promise<void>;
+}
+/**
+ * Class that manages all connections to Telegram servers.
+ */
+export declare class NetworkManager {
+    readonly params: NetworkManagerParams & NetworkManagerExtraParams;
+    readonly config: ConfigManager;
+    readonly _log: Logger;
+    readonly _storage: StorageManager;
+    readonly _initConnectionParams: tl.RawInitConnectionRequest;
+    readonly _transportFactory: TransportFactory;
+    readonly _reconnectionStrategy: ReconnectionStrategy<PersistentConnectionParams>;
+    readonly _connectionCount: ConnectionCountDelegate;
+    protected readonly _dcConnections: Map<number, DcConnectionManager>;
+    protected _primaryDc?: DcConnectionManager;
+    private _updateHandler;
+    constructor(params: NetworkManagerParams & NetworkManagerExtraParams, config: ConfigManager);
+    private _findDcOptions;
+    private _resetOnNetworkChange?;
+    private _switchPrimaryDc;
+    private _dcCreationPromise;
+    _getOtherDc(dcId: number): Promise<DcConnectionManager>;
+    /**
+     * Perform initial connection to the default DC
+     *
+     * @param defaultDcs  Default DCs to connect to
+     */
+    connect(defaultDcs: DcOptions): Promise<void>;
+    private _pendingExports;
+    private _exportAuthTo;
+    setIsPremium(isPremium: boolean): void;
+    notifyLoggedIn(auth: tl.auth.TypeAuthorization | tl.RawUser): tl.RawUser;
+    notifyLoggedOut(): void;
+    notifyNetworkChanged(connected: boolean): void;
+    resetSessions(): void;
+    private _onConfigChanged;
+    changePrimaryDc(newDc: number): Promise<void>;
+    readonly call: <T extends tl.RpcMethod>(message: T, params?: RpcCallOptions) => Promise<tl.RpcCallReturn[T['_']] | mtp.RawMt_rpc_error>;
+    private _composeCall;
+    private _call;
+    changeTransport(factory: TransportFactory): void;
+    getPoolSize(kind: ConnectionKind, dcId?: number): number;
+    getPrimaryDcId(): number;
+    destroy(): Promise<void>;
+    getMtprotoMessageId(): Long;
+}

package/network/persistent-connection.d.ts

@@ -0,0 +1,52 @@
+import { default as EventEmitter } from 'node:events';
+import { BasicDcOption, ICryptoProvider, Logger } from '../utils/index.js';
+import { ReconnectionStrategy } from './reconnection.js';
+import { ITelegramTransport, TransportFactory } from './transports/index.js';
+export interface PersistentConnectionParams {
+    crypto: ICryptoProvider;
+    transportFactory: TransportFactory;
+    dc: BasicDcOption;
+    testMode: boolean;
+    reconnectionStrategy: ReconnectionStrategy<PersistentConnectionParams>;
+    inactivityTimeout?: number;
+}
+/**
+ * Base class for persistent connections.
+ * Only used for {@link PersistentConnection} and used as a mean of code splitting.
+ * This class doesn't know anything about MTProto, it just manages the transport.
+ */
+export declare abstract class PersistentConnection extends EventEmitter {
+    readonly log: Logger;
+    private _uid;
+    readonly params: PersistentConnectionParams;
+    protected _transport: ITelegramTransport;
+    private _sendOnceConnected;
+    private _lastError;
+    private _consequentFails;
+    private _previousWait;
+    private _reconnectionTimeout;
+    private _shouldReconnectImmediately;
+    protected _disconnectedManually: boolean;
+    private _inactivityTimeout;
+    private _inactive;
+    _destroyed: boolean;
+    _usable: boolean;
+    protected abstract onConnected(): void;
+    protected abstract onError(err: Error): void;
+    protected abstract onMessage(data: Uint8Array): void;
+    protected constructor(params: PersistentConnectionParams, log: Logger);
+    get isConnected(): boolean;
+    changeTransport(factory: TransportFactory): void;
+    onTransportReady(): void;
+    protected onConnectionUsable(): void;
+    onTransportError(err: Error): void;
+    onTransportClose(): void;
+    connect(): void;
+    reconnect(): void;
+    disconnectManual(): Promise<void>;
+    destroy(): Promise<void>;
+    protected _rescheduleInactivity(): void;
+    protected _onInactivityTimeout(): void;
+    setInactivityTimeout(timeout?: number): void;
+    send(data: Uint8Array): Promise<void>;
+}

package/network/persistent-connection.test.d.ts

@@ -0,0 +1 @@
+export {};

package/network/server-salt.d.ts

@@ -0,0 +1,12 @@
+import { default as Long } from 'long';
+import { mtp } from '@mtcute/tl';
+export declare class ServerSaltManager {
+    private _futureSalts;
+    currentSalt: Long;
+    isFetching: boolean;
+    shouldFetchSalts(): boolean;
+    setFutureSalts(salts: mtp.RawMt_future_salt[]): void;
+    private _timer?;
+    private _scheduleNext;
+    destroy(): void;
+}

package/network/session-connection.d.ts

@@ -0,0 +1,79 @@
+import { tl } from '@mtcute/tl';
+import { TlReaderMap, TlWriterMap } from '@mtcute/tl-runtime';
+import { MtprotoSession } from './mtproto-session.js';
+import { PersistentConnectionParams, PersistentConnection } from './persistent-connection.js';
+import { ServerSaltManager } from './server-salt.js';
+export interface SessionConnectionParams extends PersistentConnectionParams {
+    initConnection: tl.RawInitConnectionRequest;
+    inactivityTimeout?: number;
+    enableErrorReporting: boolean;
+    layer: number;
+    disableUpdates?: boolean;
+    withUpdates?: boolean;
+    isMainConnection: boolean;
+    isMainDcConnection: boolean;
+    usePfs?: boolean;
+    salts: ServerSaltManager;
+    readerMap: TlReaderMap;
+    writerMap: TlWriterMap;
+}
+/**
+ * A connection to a single DC.
+ */
+export declare class SessionConnection extends PersistentConnection {
+    readonly _session: MtprotoSession;
+    readonly params: SessionConnectionParams;
+    private _flushTimer;
+    private _queuedDestroySession;
+    private _pendingWaitForUnencrypted;
+    private _usePfs;
+    private _isPfsBindingPending;
+    private _isPfsBindingPendingInBackground;
+    private _pfsUpdateTimeout?;
+    private _inactivityPendingFlush;
+    private _readerMap;
+    private _writerMap;
+    private _crypto;
+    private _salts;
+    constructor(params: SessionConnectionParams, _session: MtprotoSession);
+    private _online;
+    getAuthKey(temp?: boolean): Uint8Array | null;
+    setUsePfs(usePfs: boolean): void;
+    onTransportClose(): void;
+    destroy(): Promise<void>;
+    reset(forever?: boolean): void;
+    onConnected(): void;
+    protected onError(error: Error): void;
+    protected onConnectionUsable(): void;
+    _authorize(): void;
+    private _authorizePfs;
+    waitForUnencryptedMessage(timeout?: number): Promise<Uint8Array>;
+    protected onMessage(data: Uint8Array): void;
+    private _handleRawMessage;
+    private _handleMessage;
+    private _onRpcResult;
+    private _processPendingChainedFails;
+    private _onMessageAcked;
+    private _onAllFailed;
+    private _onMessageFailed;
+    private _registerOutgoingMsgId;
+    private _onPong;
+    private _onBadServerSalt;
+    private _onBadMsgNotification;
+    private _onNewSessionCreated;
+    private _onMessageInfo;
+    private _onMessagesInfo;
+    private _onMsgsStateInfo;
+    private _onFutureSalts;
+    private _onDestroySessionResult;
+    private _enqueueRpc;
+    _resetSession(): void;
+    private _sendAck;
+    sendRpc<T extends tl.RpcMethod>(request: T, timeout?: number, abortSignal?: AbortSignal, chainId?: string | number): Promise<tl.RpcCallReturn[T['_']]>;
+    notifyNetworkChanged(online: boolean): void;
+    private _cancelRpc;
+    protected _onInactivityTimeout(): void;
+    flushWhenIdle(): void;
+    private _flush;
+    private _doFlush;
+}

package/network/transports/abstract.d.ts

@@ -0,0 +1,97 @@
+import { default as EventEmitter } from 'node:events';
+import { tl } from '@mtcute/tl';
+import { MaybePromise } from '../../types/index.js';
+import { BasicDcOption, ICryptoProvider, Logger } from '../../utils/index.js';
+/** Current state of the transport */
+export declare enum TransportState {
+    /**
+     * Transport has no active connections nor trying to connect to anything
+     * Can be a result of network failure, close() call, or connect() call was
+     * never called on this instance of Transport.
+     *
+     * This state is usually immediately handled by more higher-level components,
+     * thus rarely seen
+     */
+    Idle = "idle",
+    /**
+     * Transport has no active connections, but is trying to connect to something
+     */
+    Connecting = "connecting",
+    /**
+     * Transport has an active connection
+     */
+    Ready = "ready"
+}
+/**
+ * Interface implementing a transport to interact with Telegram servers.
+ *
+ * Events:
+ *  - `ready` event is emitted once connection has been established: `() => void`
+ *  - `close` event is emitted once connection has been closed: `() => void`
+ *  - `error` event is event is emitted when there was some error
+ *    (either mtproto related or network related): `(error: Error) => void`
+ *  - `message` event is emitted when a mtproto message is received: `(message: Buffer) => void`
+ */
+export interface ITelegramTransport extends EventEmitter {
+    /** returns current state */
+    state(): TransportState;
+    /** returns current DC. should return null if state == IDLE */
+    currentDc(): BasicDcOption | null;
+    /**
+     * Start trying to connect to a specified DC.
+     * Will throw an error if state != IDLE
+     */
+    connect(dc: BasicDcOption, testMode: boolean): void;
+    /** call to close existing connection to some DC */
+    close(): MaybePromise<void>;
+    /** send a message */
+    send(data: Uint8Array): Promise<void>;
+    /**
+     * Provides crypto and logging for the transport.
+     * Not done in constructor to simplify factory.
+     *
+     * This method is called before any other.
+     */
+    setup?(crypto: ICryptoProvider, log: Logger): void;
+    getMtproxyInfo?(): tl.RawInputClientProxy;
+}
+/** Transport factory function */
+export type TransportFactory = () => ITelegramTransport;
+/**
+ * Interface declaring handling of received packets.
+ * When receiving a packet, its content is sent to feed(),
+ * and codec is supposed to emit `packet` or `error` event when packet is parsed.
+ */
+export interface IPacketCodec {
+    /** Initial tag of the codec. Will be sent immediately once connected. */
+    tag(): MaybePromise<Uint8Array>;
+    /** Encodes and frames a single packet */
+    encode(packet: Uint8Array): MaybePromise<Uint8Array>;
+    /** Feed packet to the codec. Once packet is processed, codec is supposed to emit `packet` or `error` */
+    feed(data: Uint8Array): void;
+    /** Reset codec state (for example, reset buffer) */
+    reset(): void;
+    /** Remove all listeners from a codec, used to safely dispose it */
+    removeAllListeners(): void;
+    /**
+     * Emitted when a packet containing a
+     * (Transport error)[https://core.telegram.org/mtproto/mtproto-transports#transport-errors] is encountered.
+     */
+    on(event: 'error', handler: (error: Error) => void): void;
+    on(event: 'packet', handler: (packet: Uint8Array) => void): void;
+    /**
+     * For codecs that use crypto functions and/or logging.
+     * This method is called before any other.
+     */
+    setup?(crypto: ICryptoProvider, log: Logger): void;
+}
+/**
+ * Error that represents an error in an underlying transport
+ * (and usually means either server-side problems or bug in library)
+ *
+ * More: https://core.telegram.org/mtproto/mtproto-transports#transport-errors
+ */
+export declare class TransportError extends Error {
+    code: number;
+    constructor(code: number);
+}

package/network/transports/intermediate.d.ts

@@ -0,0 +1,23 @@
+import { ICryptoProvider } from '../../utils/index.js';
+import { IPacketCodec } from './abstract.js';
+import { StreamedCodec } from './streamed.js';
+/**
+ * Intermediate packet codec.
+ * See https://core.telegram.org/mtproto/mtproto-transports#intermediate
+ */
+export declare class IntermediatePacketCodec extends StreamedCodec implements IPacketCodec {
+    tag(): Uint8Array;
+    encode(packet: Uint8Array): Uint8Array;
+    protected _packetAvailable(): boolean;
+    protected _handlePacket(): boolean;
+}
+/**
+ * Padded intermediate packet codec.
+ * See https://core.telegram.org/mtproto/mtproto-transports#padded-intermediate
+ */
+export declare class PaddedIntermediatePacketCodec extends IntermediatePacketCodec {
+    tag(): Uint8Array;
+    private _crypto;
+    setup?(crypto: ICryptoProvider): void;
+    encode(packet: Uint8Array): Uint8Array;
+}

package/network/transports/intermediate.test.d.ts

@@ -0,0 +1 @@
+export {};

package/network/transports/obfuscated.d.ts

@@ -0,0 +1,18 @@
+import { IPacketCodec } from './abstract.js';
+import { WrappedCodec } from './wrapped.js';
+export interface MtProxyInfo {
+    dcId: number;
+    secret: Uint8Array;
+    test: boolean;
+    media: boolean;
+}
+export declare class ObfuscatedPacketCodec extends WrappedCodec implements IPacketCodec {
+    private _encryptor?;
+    private _decryptor?;
+    private _proxy?;
+    constructor(inner: IPacketCodec, proxy?: MtProxyInfo);
+    tag(): Promise<Uint8Array>;
+    encode(packet: Uint8Array): Promise<Uint8Array>;
+    feed(data: Uint8Array): void;
+    reset(): void;
+}

package/network/transports/obfuscated.test.d.ts

@@ -0,0 +1 @@
+export {};

package/network/transports/streamed.d.ts

@@ -0,0 +1,23 @@
+import { default as EventEmitter } from 'node:events';
+/**
+ * Base for streamed codecs.
+ *
+ * Streamed means that MTProto packet can be divided into
+ * multiple transport packets.
+ */
+export declare abstract class StreamedCodec extends EventEmitter {
+    protected _stream: Uint8Array;
+    /**
+     * Should return whether a full packet is available
+     * in `_stream` buffer
+     */
+    protected abstract _packetAvailable(): boolean;
+    /**
+     * Handle a single (!) packet from `_stream` and emit `packet` or `error`.
+     *
+     * Should return true if there are more packets available, false otherwise
+     */
+    protected abstract _handlePacket(): boolean;
+    feed(data: Uint8Array): void;
+    reset(): void;
+}

package/network/transports/wrapped.d.ts

@@ -0,0 +1,10 @@
+import { default as EventEmitter } from 'node:events';
+import { ICryptoProvider, Logger } from '../../utils/index.js';
+import { IPacketCodec } from './abstract.js';
+export declare abstract class WrappedCodec extends EventEmitter {
+    protected _crypto: ICryptoProvider;
+    protected _inner: IPacketCodec;
+    constructor(inner: IPacketCodec);
+    removeAllListeners(): this;
+    setup(crypto: ICryptoProvider, log: Logger): void;
+}