@mt-tl/server 0.1.0

package/src/tl/layered-registry.ts

@@ -0,0 +1,132 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import type { TlDef } from '@mt-tl/tl'
+import { parseType } from '@mt-tl/tl'
+import type { TlValue } from '@mt-tl/tl'
+
+interface RawDef {
+    id: string
+    predicate?: string
+    method?: string
+    params: Array<{ name: string; type: string }>
+    type: string
+}
+interface RawSchema {
+    constructors: RawDef[]
+    methods: RawDef[]
+}
+
+interface LayerSchema {
+    byName: Map<string, TlDef>
+}
+
+/**
+ * Per-layer schema snapshots, used to encode a result/update with the
+ * constructor id and fields valid for a client's negotiated layer (decoding
+ * stays global by id). Also answers whether a value is representable at a layer
+ * — a pushed update whose type doesn't exist there must be substituted/dropped.
+ */
+export class LayeredRegistry {
+    private layers = new Map<number, LayerSchema>()
+    private sortedLayers: number[] = []
+
+    addLayer(layer: number, defs: TlDef[]): void {
+        const byName = new Map<string, TlDef>()
+        for (const def of defs) if (!byName.has(def.name)) byName.set(def.name, def)
+        this.layers.set(layer, { byName })
+        this.sortedLayers = [...this.layers.keys()].sort((a, b) => a - b)
+    }
+
+    hasLayers(): boolean {
+        return this.sortedLayers.length > 0
+    }
+
+    /** Every distinct def across all layers (by id) — for the decode-union registry. */
+    allDefs(): TlDef[] {
+        const seen = new Set<string>()
+        const out: TlDef[] = []
+        for (const { byName } of this.layers.values()) {
+            for (const def of byName.values()) {
+                if (seen.has(def.id)) continue
+                seen.add(def.id)
+                out.push(def)
+            }
+        }
+        return out
+    }
+
+    layerNumbers(): number[] {
+        return [...this.sortedLayers]
+    }
+
+    /** Largest available layer <= requested (or the smallest if requested is below all). */
+    resolveLayer(requested: number): number | undefined {
+        if (!this.sortedLayers.length) return undefined
+        let best: number | undefined
+        for (const layer of this.sortedLayers) {
+            if (layer <= requested) best = layer
+            else break
+        }
+        return best ?? this.sortedLayers[0]
+    }
+
+    resolve(name: string, layer: number): TlDef | undefined {
+        const l = this.resolveLayer(layer)
+        if (l === undefined) return undefined
+        return this.layers.get(l)?.byName.get(name)
+    }
+
+    /** True iff every constructed type in the value tree exists at `layer`. */
+    representable(value: TlValue, layer: number): boolean {
+        if (value === null || value === undefined) return true
+        if (Array.isArray(value)) return value.every(v => this.representable(v, layer))
+        if (Buffer.isBuffer(value)) return true
+        if (typeof value === 'object') {
+            const obj = value as Record<string, unknown>
+            if (typeof obj._ === 'string') {
+                if (!this.resolve(obj._, layer)) return false
+                for (const [k, v] of Object.entries(obj)) {
+                    if (k !== '_' && !this.representable(v as TlValue, layer)) return false
+                }
+            }
+            return true
+        }
+        return true // primitives, bigint, boolean, string, number
+    }
+}
+
+function rawToDef(raw: RawDef, kind: 'constructor' | 'method'): TlDef {
+    const id = raw.id.toLowerCase().padStart(8, '0')
+    return {
+        id,
+        idNum: parseInt(id, 16) >>> 0,
+        name: (raw.predicate ?? raw.method)!,
+        kind,
+        params: raw.params.map(p => ({ name: p.name, raw: p.type, type: parseType(p.type) })),
+        type: raw.type,
+        isProtocol: false,
+    }
+}
+
+/**
+ * Loads `scheme_<layer>.json` snapshots from a directory into a
+ * {@link LayeredRegistry}. A missing directory yields an empty registry
+ * (layered encoding then disabled — the gateway falls back to single-schema).
+ */
+export function loadLayeredRegistry(dir: string): LayeredRegistry {
+    const registry = new LayeredRegistry()
+    if (!existsSync(dir)) return registry
+
+    for (const file of readdirSync(dir)) {
+        const m = file.match(/_(\d+)\.json$/)
+        if (!m) continue
+        const layer = Number(m[1])
+        const raw = JSON.parse(readFileSync(join(dir, file), 'utf-8')) as RawSchema
+        const defs = [
+            ...raw.constructors.map(c => rawToDef(c, 'constructor')),
+            ...(raw.methods ?? []).map(c => rawToDef(c, 'method')),
+        ]
+        registry.addLayer(layer, defs)
+    }
+    return registry
+}

package/src/tl/protocol.ts

@@ -0,0 +1,146 @@
+import type { TlObject } from '@mt-tl/tl'
+
+/**
+ * Typed views over the immutable MTProto protocol/service constructors.
+ *
+ * These are the ~30 types the gateway reads/writes directly during the
+ * handshake, session setup and service-message handling. They are still
+ * encoded/decoded by the generic {@link TlCodec} (the constructors live in the
+ * registry); these interfaces just give the gateway code type-safety when it
+ * builds or inspects them. `_` is the constructor predicate.
+ */
+
+// --- auth key exchange ------------------------------------------------------
+
+export interface ResPQ extends TlObject {
+    _: 'resPQ'
+    nonce: Buffer // int128
+    server_nonce: Buffer // int128
+    pq: Buffer // bytes
+    server_public_key_fingerprints: bigint[] // Vector<long>
+}
+
+export interface PQInnerData extends TlObject {
+    _: 'p_q_inner_data' | 'p_q_inner_data_dc' | 'p_q_inner_data_temp' | 'p_q_inner_data_temp_dc'
+    pq: Buffer
+    p: Buffer
+    q: Buffer
+    nonce: Buffer
+    server_nonce: Buffer
+    new_nonce: Buffer // int256
+    dc?: number
+    expires_in?: number
+}
+
+export interface ServerDHParamsOk extends TlObject {
+    _: 'server_DH_params_ok'
+    nonce: Buffer
+    server_nonce: Buffer
+    encrypted_answer: Buffer
+}
+
+export interface ServerDHParamsFail extends TlObject {
+    _: 'server_DH_params_fail'
+    nonce: Buffer
+    server_nonce: Buffer
+    new_nonce_hash: Buffer
+}
+
+export interface ServerDHInnerData extends TlObject {
+    _: 'server_DH_inner_data'
+    nonce: Buffer
+    server_nonce: Buffer
+    g: number
+    dh_prime: Buffer
+    g_a: Buffer
+    server_time: number
+}
+
+export interface ClientDHInnerData extends TlObject {
+    _: 'client_DH_inner_data'
+    nonce: Buffer
+    server_nonce: Buffer
+    retry_id: bigint
+    g_b: Buffer
+}
+
+export interface DhGenOk extends TlObject {
+    _: 'dh_gen_ok'
+    nonce: Buffer
+    server_nonce: Buffer
+    new_nonce_hash1: Buffer
+}
+
+// --- session / service ------------------------------------------------------
+
+export interface NewSessionCreated extends TlObject {
+    _: 'new_session_created'
+    first_msg_id: bigint
+    unique_id: bigint
+    server_salt: bigint
+}
+
+export interface RpcResult extends TlObject {
+    _: 'rpc_result'
+    req_msg_id: bigint
+    result: TlObject | boolean
+}
+
+export interface RpcError extends TlObject {
+    _: 'rpc_error'
+    error_code: number
+    error_message: string
+}
+
+export interface Pong extends TlObject {
+    _: 'pong'
+    msg_id: bigint
+    ping_id: bigint
+}
+
+export interface MsgsAck extends TlObject {
+    _: 'msgs_ack'
+    msg_ids: bigint[]
+}
+
+export interface BadServerSalt extends TlObject {
+    _: 'bad_server_salt'
+    bad_msg_id: bigint
+    bad_msg_seqno: number
+    error_code: number
+    new_server_salt: bigint
+}
+
+export interface BadMsgNotification extends TlObject {
+    _: 'bad_msg_notification'
+    bad_msg_id: bigint
+    bad_msg_seqno: number
+    error_code: number
+}
+
+export interface MsgContainer extends TlObject {
+    _: 'msg_container'
+    messages: TlObject[]
+}
+
+/** Well-known protocol constructor predicates, for branching in the pipeline. */
+export const Predicate = {
+    req_pq: 'req_pq',
+    req_pq_multi: 'req_pq_multi',
+    req_DH_params: 'req_DH_params',
+    set_client_DH_params: 'set_client_DH_params',
+    ping: 'ping',
+    ping_delay_disconnect: 'ping_delay_disconnect',
+    msgs_ack: 'msgs_ack',
+    msgs_state_req: 'msgs_state_req',
+    rpc_drop_answer: 'rpc_drop_answer',
+    destroy_session: 'destroy_session',
+    get_future_salts: 'get_future_salts',
+    http_wait: 'http_wait',
+    msg_container: 'msg_container',
+    gzip_packed: 'gzip_packed',
+    invokeWithLayer: 'invokeWithLayer',
+    invokeWithoutUpdates: 'invokeWithoutUpdates',
+    invokeAfterMsg: 'invokeAfterMsg',
+    initConnection: 'initConnection',
+} as const

package/src/tl/reader.ts

@@ -0,0 +1,99 @@
+import { toBigIntLE } from '../util/bytes.js'
+
+export const BOOL_TRUE_ID = 0x997275b5
+export const BOOL_FALSE_ID = 0xbc799737
+export const VECTOR_ID = 0x1cb5c415
+
+/**
+ * Low-level reader for the TL wire format. Exposes only primitive reads; the
+ * codec drives constructor-id dispatch, vectors and flags. Ported from the
+ * existing `protocolBuffer.js` (same little-endian / padding rules).
+ */
+export class TlReader {
+    private pos = 0
+
+    constructor(private readonly buf: Buffer) {}
+
+    get position(): number {
+        return this.pos
+    }
+
+    get remaining(): number {
+        return this.buf.length - this.pos
+    }
+
+    private expect(len: number): void {
+        if (this.buf.length < this.pos + len) {
+            throw new Error(`TL read out of bounds: need ${len}, have ${this.remaining}`)
+        }
+    }
+
+    read(len: number): Buffer {
+        this.expect(len)
+        const out = this.buf.subarray(this.pos, this.pos + len)
+        this.pos += len
+        return out
+    }
+
+    skip(len: number): void {
+        this.expect(len)
+        this.pos += len
+    }
+
+    readUInt8(): number {
+        this.expect(1)
+        return this.buf.readUInt8(this.pos++)
+    }
+
+    readUInt32(): number {
+        this.expect(4)
+        const v = this.buf.readUInt32LE(this.pos)
+        this.pos += 4
+        return v
+    }
+
+    readInt32(): number {
+        this.expect(4)
+        const v = this.buf.readInt32LE(this.pos)
+        this.pos += 4
+        return v
+    }
+
+    /** TL `long` — 8 bytes LE, read as an unsigned bigint (matches existing server). */
+    readLong(): bigint {
+        return toBigIntLE(this.read(8))
+    }
+
+    readDouble(): number {
+        this.expect(8)
+        const v = this.buf.readDoubleLE(this.pos)
+        this.pos += 8
+        return v
+    }
+
+    readInt128(): Buffer {
+        return Buffer.from(this.read(16))
+    }
+
+    readInt256(): Buffer {
+        return Buffer.from(this.read(32))
+    }
+
+    /** TL `bytes`/`string` — length-prefixed with 4-byte alignment padding. */
+    readBytes(): Buffer {
+        let extra = 1
+        let len = this.readUInt8()
+        if (len >= 254) {
+            len = this.readUInt8() + this.readUInt8() * 256 + this.readUInt8() * 65536
+            extra = 4
+        }
+        const out = Buffer.from(this.read(len))
+        const rem = (len + extra) % 4
+        if (rem > 0) this.skip(4 - rem)
+        return out
+    }
+
+    readString(): string {
+        return this.readBytes().toString('utf-8')
+    }
+}

package/src/tl/registry.ts

@@ -0,0 +1,78 @@
+import type { TlDef } from '@mt-tl/tl'
+import { parseSchemaDir } from '@mt-tl/tl'
+
+/**
+ * Resolves TL definitions both ways: by wire constructor id (for decoding) and
+ * by name (for encoding a result the backend returned as `{ _: name, ... }`).
+ *
+ * Hand-written protocol/service classes register a {@link ProtocolCodec} for
+ * their id so the pipeline can read/write them with typed code; everything else
+ * falls through to the generic, IR-driven codec.
+ */
+export interface ProtocolCodec {
+    id: string
+    name: string
+    read(reader: import('./reader.js').TlReader): unknown
+    write(writer: import('./writer.js').TlWriter, value: unknown): void
+}
+
+export class TlRegistry {
+    private byId = new Map<number, TlDef>()
+    private byName = new Map<string, TlDef>()
+    private protocolCodecs = new Map<number, ProtocolCodec>()
+
+    register(def: TlDef): void {
+        if (!this.byId.has(def.idNum)) this.byId.set(def.idNum, def)
+        if (!this.byName.has(def.name)) this.byName.set(def.name, def)
+    }
+
+    registerProtocolCodec(codec: ProtocolCodec): void {
+        this.protocolCodecs.set(parseInt(codec.id, 16) >>> 0, codec)
+    }
+
+    getById(idNum: number): TlDef | undefined {
+        return this.byId.get(idNum >>> 0)
+    }
+
+    getByName(name: string): TlDef | undefined {
+        return this.byName.get(name)
+    }
+
+    getProtocolCodec(idNum: number): ProtocolCodec | undefined {
+        return this.protocolCodecs.get(idNum >>> 0)
+    }
+
+    get size(): number {
+        return this.byId.size
+    }
+}
+
+export interface LoadSchemaResult {
+    registry: TlRegistry
+    constructors: number
+    methods: number
+    crcMismatches: number
+}
+
+/**
+ * Loads + merges one or more `.tl` schema directories into a single registry.
+ * The gateway merges the framework's protocol schema with the app's business
+ * schema — pass protocol first (earlier dirs win a name/id clash).
+ */
+export function loadSchema(dirs: string | string[]): LoadSchemaResult {
+    const list = Array.isArray(dirs) ? dirs : [dirs]
+    const registry = new TlRegistry()
+    let constructors = 0
+    let methods = 0
+    let crcMismatches = 0
+    for (const dir of list) {
+        const parsed = parseSchemaDir(dir)
+        crcMismatches += parsed.crcMismatches.length
+        for (const def of parsed.defs) {
+            registry.register(def)
+            if (def.kind === 'method') methods++
+            else constructors++
+        }
+    }
+    return { registry, constructors, methods, crcMismatches }
+}

package/src/tl/writer.ts

@@ -0,0 +1,104 @@
+import { toBufferLE } from '../util/bytes.js'
+import { BOOL_FALSE_ID, BOOL_TRUE_ID } from './reader.js'
+
+/**
+ * Low-level writer for the TL wire format. Grows its backing buffer in 1 KiB
+ * steps. Ported from the existing `protocolBuffer.js`.
+ */
+export class TlWriter {
+    private buf: Buffer
+    private pos = 0
+    private readonly step = 1024
+
+    constructor(preallocate = 1024) {
+        this.buf = Buffer.allocUnsafe(preallocate)
+    }
+
+    private alloc(len: number): void {
+        if (this.buf.length >= this.pos + len) return
+        let target = this.buf.length + this.step
+        while (target < this.pos + len) target += this.step
+        const next = Buffer.allocUnsafe(target)
+        this.buf.copy(next, 0, 0, this.pos)
+        this.buf = next
+    }
+
+    writeRaw(val: Buffer, len = val.length): this {
+        this.alloc(len)
+        val.copy(this.buf, this.pos, 0, len)
+        this.pos += len
+        return this
+    }
+
+    writeUInt8(val: number): this {
+        this.alloc(1)
+        this.buf.writeUInt8(val & 0xff, this.pos++)
+        return this
+    }
+
+    writeUInt32(val: number): this {
+        this.alloc(4)
+        this.buf.writeUInt32LE(val >>> 0, this.pos)
+        this.pos += 4
+        return this
+    }
+
+    writeInt32(val: number): this {
+        this.alloc(4)
+        this.buf.writeInt32LE(val | 0, this.pos)
+        this.pos += 4
+        return this
+    }
+
+    writeLong(val: bigint): this {
+        return this.writeRaw(toBufferLE(BigInt(val), 8), 8)
+    }
+
+    writeDouble(val: number): this {
+        this.alloc(8)
+        this.buf.writeDoubleLE(val, this.pos)
+        this.pos += 8
+        return this
+    }
+
+    /** 16/32 raw bytes for int128/int256 (left-padded if a short buffer is given). */
+    writeFixed(val: Buffer, len: number): this {
+        if (val.length === len) return this.writeRaw(val, len)
+        const padded = Buffer.alloc(len)
+        val.copy(padded, len - val.length)
+        return this.writeRaw(padded, len)
+    }
+
+    writeBytes(val: Buffer): this {
+        let len: number
+        if (val.length < 254) {
+            this.writeUInt8(val.length)
+            len = 1
+        } else {
+            // 0xfe marker + 3-byte LE length
+            this.writeUInt8(254)
+            this.writeUInt32(val.length)
+            this.pos--
+            len = 4
+        }
+        this.writeRaw(val)
+        len += val.length
+        while (len % 4 !== 0) {
+            this.writeUInt8(0)
+            len++
+        }
+        return this
+    }
+
+    writeString(val: string): this {
+        return this.writeBytes(val ? Buffer.from(val, 'utf-8') : Buffer.alloc(0))
+    }
+
+    writeBool(val: boolean): this {
+        return this.writeUInt32(val ? BOOL_TRUE_ID : BOOL_FALSE_ID)
+    }
+
+    toBuffer(): Buffer {
+        return Buffer.from(this.buf.subarray(0, this.pos))
+    }
+}

package/src/transport/connection-registry.ts

@@ -0,0 +1,91 @@
+import type { Connection } from './connection.js'
+
+/**
+ * Per-node map of authorized subject -> live connections, used to deliver
+ * server-pushed updates to the right sockets. A subject (internal user id) may
+ * have several connections (multiple devices/sessions) on one node.
+ */
+export class ConnectionRegistry {
+    private bySubject = new Map<string, Set<Connection>>()
+    private connSubject = new Map<Connection, string>()
+    private byAuthKey = new Map<string, Set<Connection>>()
+    private connAuthKey = new Map<Connection, string>()
+
+    register(subject: string, conn: Connection): void {
+        const prev = this.connSubject.get(conn)
+        if (prev !== undefined && prev !== subject) removeFrom(this.bySubject, prev, conn)
+        this.connSubject.set(conn, subject)
+        addTo(this.bySubject, subject, conn)
+    }
+
+    /** Index a connection by its auth key, for delivery before/without a subject. */
+    registerAuthKey(authKeyId: string, conn: Connection): void {
+        if (this.connAuthKey.get(conn) === authKeyId) return
+        this.connAuthKey.set(conn, authKeyId)
+        addTo(this.byAuthKey, authKeyId, conn)
+    }
+
+    /** Remove a connection from both indexes; returns the keys it was held under. */
+    unregister(conn: Connection): { subject?: string; authKeyId?: string } {
+        const subject = this.connSubject.get(conn)
+        if (subject !== undefined) {
+            this.connSubject.delete(conn)
+            removeFrom(this.bySubject, subject, conn)
+        }
+        const authKeyId = this.connAuthKey.get(conn)
+        if (authKeyId !== undefined) {
+            this.connAuthKey.delete(conn)
+            removeFrom(this.byAuthKey, authKeyId, conn)
+        }
+        return { subject, authKeyId }
+    }
+
+    subjectOf(conn: Connection): string | undefined {
+        return this.connSubject.get(conn)
+    }
+
+    hasSubject(subject: string): boolean {
+        return this.bySubject.has(subject)
+    }
+    hasAuthKey(authKeyId: string): boolean {
+        return this.byAuthKey.has(authKeyId)
+    }
+
+    getBySubject(subject: string): Connection[] {
+        const set = this.bySubject.get(subject)
+        return set ? [...set] : []
+    }
+    getByAuthKey(authKeyId: string): Connection[] {
+        const set = this.byAuthKey.get(authKeyId)
+        return set ? [...set] : []
+    }
+
+    /** All subjects with at least one local connection (for presence heartbeat). */
+    subjects(): string[] {
+        return [...this.bySubject.keys()]
+    }
+    /** All auth keys with at least one local connection (for presence heartbeat). */
+    authKeys(): string[] {
+        return [...this.byAuthKey.keys()]
+    }
+
+    get size(): number {
+        return this.connSubject.size
+    }
+}
+
+function addTo<K>(map: Map<K, Set<Connection>>, key: K, conn: Connection): void {
+    let set = map.get(key)
+    if (!set) {
+        set = new Set()
+        map.set(key, set)
+    }
+    set.add(conn)
+}
+
+function removeFrom<K>(map: Map<K, Set<Connection>>, key: K, conn: Connection): void {
+    const set = map.get(key)
+    if (!set) return
+    set.delete(conn)
+    if (set.size === 0) map.delete(key)
+}