@afterlink/server 1.0.0 → 1.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@afterlink/server",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "AfterLink Protocol Server SDK - TCP server with routing, middleware, and pub/sub",
   "main": "src/index.js",
   "license": "MIT",
@@ -29,7 +29,8 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@afterlink/core": "1.0.0"
+    "@afterlink/core": "^1.1.0",
+    "selfsigned": "^5.5.0"
   },
   "devDependencies": {
     "vitest": "^1.6.0"

package/src/Connection.js

@@ -2,6 +2,7 @@ const {
   Frame,
   FrameTypes: { HELLO, HELLO_ACK, ERROR },
   Serializer,
+  compression,
 } = require('@afterlink/core');
 const FrameAccumulator = require('./FrameAccumulator');
 
@@ -14,6 +15,20 @@ class Connection {
     this._id = `conn_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
     this._closed = false;
 
+    // Compression state (negotiated during handshake)
+    this._compression = {
+      enabled: false,
+      algorithm: 'none',
+      level: 6,
+      threshold: 1024,
+    };
+
+    // Rate limiting bucket (attached by server if enabled)
+    this._rateBucket = null;
+
+    // Active request tracking for graceful shutdown
+    this._activeRequests = new Set();
+
     try {
       this.accumulator = new FrameAccumulator(this._handleFrame.bind(this));
     } catch (err) {
@@ -56,7 +71,28 @@ class Connection {
     if (frame.type === HELLO && !this.session) {
       this._handleHandshake(frame);
     } else if (this.session) {
+      // Decompress incoming frame if compressed
+      if (compression.isCompressed(frame.flags)) {
+        try {
+          frame.payload = compression.decompress(
+            frame.payload,
+            true,
+            this._compression.algorithm
+          );
+        } catch (err) {
+          this.sendError('DECOMPRESSION_ERROR', 'Failed to decompress payload');
+          return;
+        }
+      }
+
+      // Track active requests for graceful shutdown
+      const { REQUEST } = require('@afterlink/core').FrameTypes;
+      if (frame.type === REQUEST) {
+        this._activeRequests.add(frame.messageId);
+      }
+
       this.router.dispatch(frame, this).catch((err) => {
+        this._activeRequests.delete(frame.messageId);
         this._onError(err);
       });
     } else {
@@ -74,18 +110,49 @@ class Connection {
         this._validateAuth(data.auth);
       }
 
+      // Negotiate compression
+      const serverCompression = this.options.compression || {};
+      const clientAlgorithm = data.compression || 'none';
+      const serverEnabled = serverCompression.enabled !== false;
+      const serverAlgorithm = serverCompression.algorithm || 'zlib';
+
+      // Use client's preferred algorithm if server supports it
+      let agreedAlgorithm = 'none';
+      if (serverEnabled && clientAlgorithm !== 'none') {
+        if (clientAlgorithm === serverAlgorithm || clientAlgorithm === 'brotli') {
+          agreedAlgorithm = clientAlgorithm;
+        } else if (serverAlgorithm !== 'none') {
+          agreedAlgorithm = serverAlgorithm;
+        }
+      }
+
+      this._compression = {
+        enabled: agreedAlgorithm !== 'none',
+        algorithm: agreedAlgorithm,
+        level: serverCompression.level ?? 6,
+        threshold: serverCompression.threshold ?? 1024,
+      };
+
       this.session = {
         id: sessionId,
         version: data.version || 'AL/1',
         capabilities: data.capabilities || [],
         connectedAt: new Date().toISOString(),
         remoteAddress: this.getRemoteAddress(),
+        compression: agreedAlgorithm,
       };
 
       const ackPayload = Serializer.encode({
         session_id: sessionId,
-        server_version: 'AL/1',
-        capabilities: ['streaming', 'pubsub', 'compression'],
+        server_version: 'AL/1.1',
+        capabilities: ['streaming', 'pubsub', 'compression', 'rate-limit'],
+        compression: agreedAlgorithm,
+        rateLimit: this.options.rateLimit?.enabled
+          ? {
+              requestsPerSecond: this.options.rateLimit.requestsPerSecond,
+              burstSize: this.options.rateLimit.burstSize,
+            }
+          : undefined,
       });
       this.send(HELLO_ACK, 0, frame.messageId, ackPayload);
     } catch (err) {
@@ -104,8 +171,28 @@ class Connection {
   send(type, flags, messageId, payload) {
     if (this._closed || this.socket.destroyed) return;
     try {
-      const frame = Frame.encode(type, flags, messageId, payload);
+      // Compress payload if enabled and above threshold
+      let finalPayload = payload;
+      let finalFlags = flags;
+      if (this._compression.enabled && this.session) {
+        const { data, compressed } = compression.compress(
+          payload,
+          this._compression.algorithm,
+          this._compression.level,
+          this._compression.threshold
+        );
+        finalPayload = data;
+        finalFlags = compression.setCompressedFlag(flags, compressed);
+      }
+
+      const frame = Frame.encode(type, finalFlags, messageId, finalPayload);
       this.socket.write(frame);
+
+      // Track response sent - remove from active requests
+      const { RESPONSE, ERROR } = require('@afterlink/core').FrameTypes;
+      if (type === RESPONSE || type === ERROR) {
+        this._activeRequests.delete(messageId);
+      }
     } catch (err) {
       this._onError(err);
     }

package/src/Router.js

@@ -80,7 +80,7 @@ class Router {
     }
 
     let responseSent = false;
-    const req = { body, session: connection.session, route };
+    const req = { body, session: connection.session, route, connection };
     const res = {
       send: (data) => {
         if (responseSent) return;
@@ -100,7 +100,22 @@ class Router {
       });
     } catch (err) {
       if (!responseSent) {
-        connection.sendError('INTERNAL_ERROR', err.message, messageId);
+        if (err.code === 'RATE_LIMITED') {
+          const errorPayload = Serializer.encode({
+            code: err.code,
+            message: err.message,
+            retryAfter: err.retryAfter,
+            limit: err.limit,
+            remaining: err.remaining,
+          });
+          connection.send(ERROR, 0, messageId, errorPayload);
+
+          if (err.closeConnection) {
+            connection.destroy();
+          }
+        } else {
+          connection.sendError('INTERNAL_ERROR', err.message, messageId);
+        }
       }
     }
   }

package/src/Server.js

@@ -1,4 +1,7 @@
-const net = require('net');
+const { createServerTransport, isTLSSocket, getTLSInfo } = require('./transport/tls');
+const { TokenBucket, createRateLimitMiddleware } = require('./middleware/rate-limit');
+const { GracefulShutdown } = require('./shutdown/graceful');
+
 const Connection = require('./Connection');
 const Router = require('./Router');
 
@@ -8,12 +11,48 @@ class Server {
       port: 4000,
       host: '0.0.0.0',
       maxConnections: 10000,
+      compression: {
+        enabled: false,
+        algorithm: 'zlib',
+        threshold: 1024,
+        level: 6,
+      },
+      rateLimit: {
+        enabled: false,
+        requestsPerSecond: 100,
+        burstSize: 200,
+        closeAfterViolations: null,
+        errorMessage: 'Rate limit exceeded. Please slow down.',
+        onLimited: null,
+      },
+      shutdown: {
+        drainTimeout: 5000,
+        reason: 'planned_restart',
+        notifyClients: true,
+      },
       ...config,
     };
+    // Merge nested configs deeply
+    if (config.compression) {
+      this.config.compression = { ...this.config.compression, ...config.compression };
+    }
+    if (config.rateLimit) {
+      this.config.rateLimit = { ...this.config.rateLimit, ...config.rateLimit };
+    }
+    if (config.shutdown) {
+      this.config.shutdown = { ...this.config.shutdown, ...config.shutdown };
+    }
+
     this.router = new Router();
     this.connections = new Set();
-    this.tcp = null;
+    this.transport = null;
     this._listening = false;
+    this._tlsEnabled = !!config.tls?.enabled;
+    this._shutdown = null;
+    this._eventListeners = new Map();
+
+    // Initialize graceful shutdown handler
+    this._shutdown = new GracefulShutdown(this, this.config.shutdown);
   }
 
   on(route, handler, schema = null) {
@@ -37,51 +76,147 @@ class Server {
         return reject(new Error('Server is already listening'));
       }
 
-      this.tcp = net.createServer((socket) => {
-        if (this.connections.size >= this.config.maxConnections) {
-          socket.destroy();
-          return;
+      try {
+        this.transport = createServerTransport(this.config);
+      } catch (err) {
+        return reject(err);
+      }
+
+      // Auto-add rate limiting middleware if enabled
+      if (this.config.rateLimit.enabled) {
+        const rateLimitMiddleware = createRateLimitMiddleware(this.config.rateLimit);
+        if (rateLimitMiddleware) {
+          this.router.addMiddleware(rateLimitMiddleware);
         }
+      }
 
-        socket.setKeepAlive(true, 60000);
-        socket.setNoDelay(true);
+      this.transport.on('secureConnection', (socket) => {
+        this._handleConnection(socket);
+      });
 
-        const conn = new Connection(socket, this.router, {
-          auth: this.config.auth,
-        });
-        this.connections.add(conn);
-        socket.on('close', () => this.connections.delete(conn));
+      this.transport.on('connection', (socket) => {
+        // For TLS servers, skip the raw connection event (handled by secureConnection)
+        if (this._tlsEnabled) return;
+        this._handleConnection(socket);
       });
 
-      this.tcp.on('error', (err) => {
+      this.transport.on('error', (err) => {
         if (err.code === 'EADDRINUSE') {
           reject(new Error(`Port ${port} is already in use`));
+        } else if (err.code === 'ERR_TLS_CERT_ALTNAME_INVALID') {
+          const tlsErr = new Error('TLS certificate does not match hostname');
+          tlsErr.code = 'TLS_CERT_ERROR';
+          reject(tlsErr);
         } else {
           console.error('[AfterLink] Server error:', err.message);
         }
       });
 
-      this.tcp.listen(port, this.config.host, () => {
+      this.transport.listen(port, this.config.host, () => {
         this._listening = true;
-        console.log(`[AfterLink] Server listening on ${this.config.host}:${port}`);
+        const proto = this._tlsEnabled ? 'TLS' : 'TCP';
+        console.log(`[AfterLink] ${proto} Server listening on ${this.config.host}:${port}`);
         resolve(this);
       });
     });
   }
 
-  close() {
+  _handleConnection(socket) {
+    if (this.connections.size >= this.config.maxConnections) {
+      socket.destroy();
+      return;
+    }
+
+    socket.setKeepAlive(true, 60000);
+    socket.setNoDelay(true);
+
+    const conn = new Connection(socket, this.router, {
+      auth: this.config.auth,
+      compression: this.config.compression,
+      rateLimit: this.config.rateLimit,
+    });
+
+    // Attach rate bucket if rate limiting is enabled
+    if (this.config.rateLimit.enabled) {
+      const { requestsPerSecond, burstSize } = this.config.rateLimit;
+      conn._rateBucket = new TokenBucket(burstSize, requestsPerSecond / 1000);
+    }
+
+    // Attach TLS info if available
+    if (isTLSSocket(socket)) {
+      conn.tlsInfo = getTLSInfo(socket);
+    }
+
+    this.connections.add(conn);
+    socket.on('close', () => this.connections.delete(conn));
+  }
+
+  on(routeOrEvent, handlerOrListener, schema = null) {
+    // Check if this is route registration (handler is a function with route pattern)
+    if (typeof routeOrEvent === 'string' && typeof handlerOrListener === 'function' && !this._eventListeners.has(routeOrEvent)) {
+      // Route registration
+      this.router.register(routeOrEvent, handlerOrListener, schema);
+      return this;
+    }
+    
+    // Event listener
+    const event = routeOrEvent;
+    const listener = handlerOrListener;
+    if (!this._eventListeners.has(event)) {
+      this._eventListeners.set(event, new Set());
+    }
+    this._eventListeners.get(event).add(listener);
+    return this;
+  }
+
+  off(event, listener) {
+    const listeners = this._eventListeners.get(event);
+    if (listeners) {
+      listeners.delete(listener);
+    }
+    return this;
+  }
+
+  _emit(event, data) {
+    const listeners = this._eventListeners.get(event);
+    if (listeners) {
+      for (const listener of listeners) {
+        try {
+          listener(data);
+        } catch (err) {
+          console.error(`[AfterLink] Event listener error for '${event}':`, err.message);
+        }
+      }
+    }
+  }
+
+  async close(options = {}) {
     return new Promise((resolve) => {
-      if (!this.tcp || !this._listening) {
+      if (!this.transport || !this._listening) {
         return resolve();
       }
 
       this._listening = false;
 
-      for (const conn of this.connections) {
-        conn.destroy();
+      if (options.force) {
+        // Force close - skip drain
+        for (const conn of this.connections) {
+          conn.destroy();
+        }
+        this.transport.close(() => {
+          this._emit('closed');
+          resolve();
+        });
+        return;
       }
 
-      this.tcp.close(() => resolve());
+      // Graceful shutdown
+      this._shutdown.initiate().then(() => {
+        this.transport.close(() => {
+          this._emit('closed');
+          resolve();
+        });
+      });
     });
   }
 
@@ -96,6 +231,26 @@ class Server {
   isListening() {
     return this._listening;
   }
+
+  isTLS() {
+    return this._tlsEnabled;
+  }
+
+  handleProcessSignals() {
+    process.on('SIGTERM', async () => {
+      console.log('[AfterLink] SIGTERM received — shutting down gracefully');
+      await this.close();
+      process.exit(0);
+    });
+
+    process.on('SIGINT', async () => {
+      console.log('[AfterLink] SIGINT received — shutting down gracefully');
+      await this.close();
+      process.exit(0);
+    });
+
+    return this;
+  }
 }
 
 module.exports = Server;

package/src/index.js

@@ -1,3 +1,4 @@
 const Server = require('./Server');
+const { generateDevCerts } = require('./tls/dev-certs');
 
-module.exports = { Server };
+module.exports = { Server, generateDevCerts };

package/src/middleware/rate-limit.js

@@ -0,0 +1,81 @@
+class TokenBucket {
+  constructor(capacity, refillRate) {
+    this.capacity = capacity;
+    this.refillRate = refillRate;
+    this.tokens = capacity;
+    this.lastRefill = Date.now();
+    this.violations = 0;
+  }
+
+  consume() {
+    this._refill();
+    if (this.tokens < 1) {
+      this.violations++;
+      return {
+        allowed: false,
+        retryAfter: Math.ceil((1 - this.tokens) / this.refillRate),
+      };
+    }
+    this.tokens--;
+    return { allowed: true, retryAfter: 0 };
+  }
+
+  _refill() {
+    const now = Date.now();
+    const elapsed = now - this.lastRefill;
+    this.tokens = Math.min(this.capacity, this.tokens + elapsed * this.refillRate);
+    this.lastRefill = now;
+  }
+}
+
+function createRateLimitMiddleware(options = {}) {
+  const {
+    enabled = false,
+    requestsPerSecond = 100,
+    burstSize = 200,
+    closeAfterViolations = null,
+    errorMessage = 'Rate limit exceeded. Please slow down.',
+    onLimited = null,
+  } = options;
+
+  if (!enabled) {
+    return null;
+  }
+
+  const refillRatePerMs = requestsPerSecond / 1000;
+
+  return function rateLimitMiddleware(req, next) {
+    const bucket = req.connection._rateBucket;
+    if (!bucket) {
+      return next();
+    }
+
+    const result = bucket.consume();
+
+    if (!result.allowed) {
+      const err = new Error(errorMessage);
+      err.code = 'RATE_LIMITED';
+      err.retryAfter = result.retryAfter;
+      err.limit = requestsPerSecond;
+      err.remaining = 0;
+
+      if (onLimited) {
+        try {
+          onLimited(req.connection);
+        } catch {
+          // Ignore callback errors
+        }
+      }
+
+      if (closeAfterViolations && bucket.violations >= closeAfterViolations) {
+        err.closeConnection = true;
+      }
+
+      throw err;
+    }
+
+    return next();
+  };
+}
+
+module.exports = { TokenBucket, createRateLimitMiddleware };

package/src/shutdown/graceful.js

@@ -0,0 +1,95 @@
+const { Frame, Serializer } = require('@afterlink/core');
+
+const SERVER_CLOSING = 0x11;
+
+class GracefulShutdown {
+  constructor(server, config = {}) {
+    this.server = server;
+    this.drainTimeout = config.drainTimeout ?? 5000;
+    this.reason = config.reason ?? 'planned_restart';
+    this.notifyClients = config.notifyClients !== false;
+    this._closing = false;
+    this._closed = false;
+  }
+
+  async initiate() {
+    if (this._closing || this._closed) {
+      return;
+    }
+
+    this._closing = true;
+
+    const activeConnections = this.server.connections;
+    const activeRequests = this._countActiveRequests(activeConnections);
+
+    this.server._emit('closing', {
+      activeConnections: activeConnections.size,
+      activeRequests,
+    });
+
+    if (this.notifyClients) {
+      this._broadcastClosing(activeConnections);
+    }
+
+    const drainStart = Date.now();
+    await this._waitForDrain(activeConnections);
+
+    const drainElapsed = Date.now() - drainStart;
+    if (drainElapsed >= this.drainTimeout) {
+      this.server._emit('drained', { timedOut: true });
+    } else {
+      this.server._emit('drained', { timedOut: false });
+    }
+
+    this._forceCloseRemaining(activeConnections);
+    this._closed = true;
+    this._closing = false;
+  }
+
+  _countActiveRequests(connections) {
+    let total = 0;
+    for (const conn of connections) {
+      total += conn._activeRequests?.size ?? 0;
+    }
+    return total;
+  }
+
+  _broadcastClosing(connections) {
+    const payload = Serializer.encode({
+      drainTimeout: this.drainTimeout,
+      reason: this.reason,
+    });
+
+    for (const conn of connections) {
+      try {
+        conn.send(SERVER_CLOSING, 0, 0, payload);
+      } catch {
+        // Ignore send errors during shutdown
+      }
+    }
+  }
+
+  async _waitForDrain(connections) {
+    const deadline = Date.now() + this.drainTimeout;
+
+    while (Date.now() < deadline) {
+      const active = this._countActiveRequests(connections);
+      if (active === 0) {
+        return;
+      }
+      await this._sleep(100);
+    }
+  }
+
+  _forceCloseRemaining(connections) {
+    for (const conn of connections) {
+      conn.destroy();
+    }
+  }
+
+  _sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+}
+
+module.exports = { GracefulShutdown, SERVER_CLOSING };

package/src/tls/dev-certs.js

@@ -0,0 +1,33 @@
+const selfsigned = require('selfsigned');
+
+/**
+ * Generates self-signed development certificates.
+ * Uses the `selfsigned` package for reliable X.509 generation.
+ * NEVER use these in production.
+ *
+ * @param {object} [options]
+ * @param {string} [options.commonName='afterlink-dev'] - Certificate common name
+ * @param {number} [options.days=365] - Certificate validity in days
+ * @returns {Promise<{key: Buffer, cert: Buffer}>}
+ */
+async function generateDevCerts(options = {}) {
+  const {
+    commonName = 'afterlink-dev',
+    days = 365,
+  } = options;
+
+  const attrs = [{ name: 'commonName', value: commonName }];
+
+  const pems = await selfsigned.generate(attrs, {
+    days,
+    algorithm: 'sha256',
+    keySize: 2048,
+  });
+
+  return {
+    key: Buffer.from(pems.private),
+    cert: Buffer.from(pems.cert),
+  };
+}
+
+module.exports = { generateDevCerts };

package/src/transport/tls.js

@@ -0,0 +1,86 @@
+const tls = require('tls');
+const net = require('net');
+
+/**
+ * Creates a server transport (TCP or TLS) based on configuration.
+ * @param {object} options - Server configuration
+ * @param {object} [options.tls] - TLS configuration
+ * @param {boolean} [options.tls.enabled=false] - Enable TLS encryption
+ * @param {Buffer|string} [options.tls.key] - Private key PEM buffer or path
+ * @param {Buffer|string} [options.tls.cert] - Certificate PEM buffer or path
+ * @param {Buffer|string} [options.tls.ca] - CA certificate for mutual TLS
+ * @param {boolean} [options.tls.rejectUnauthorized=true] - Reject unauthorized clients
+ * @param {string} [options.tls.minVersion='TLSv1.2'] - Minimum TLS version
+ * @param {number} [options.tls.sessionTimeout=300] - TLS session cache timeout (seconds)
+ * @returns {tls.Server|net.Server}
+ */
+function createServerTransport(options) {
+  if (options.tls?.enabled) {
+    validateTlsConfig(options.tls);
+
+    return tls.createServer({
+      key: options.tls.key,
+      cert: options.tls.cert,
+      ca: options.tls.ca,
+      requestCert: !!options.tls.ca,
+      rejectUnauthorized: options.tls.rejectUnauthorized ?? true,
+      minVersion: options.tls.minVersion ?? 'TLSv1.2',
+      sessionTimeout: options.tls.sessionTimeout ?? 300,
+    });
+  }
+
+  return net.createServer();
+}
+
+/**
+ * Validates TLS configuration and throws descriptive errors.
+ * @param {object} tlsConfig
+ * @throws {Error} TLS_CONFIG_ERROR if configuration is invalid
+ */
+function validateTlsConfig(tlsConfig) {
+  if (!tlsConfig.key) {
+    const err = new Error('TLS enabled but no private key provided');
+    err.code = 'TLS_CONFIG_ERROR';
+    throw err;
+  }
+
+  if (!tlsConfig.cert) {
+    const err = new Error('TLS enabled but no certificate provided');
+    err.code = 'TLS_CONFIG_ERROR';
+    throw err;
+  }
+}
+
+/**
+ * Checks if a socket is a TLS socket.
+ * @param {net.Socket|tls.TLSSocket} socket
+ * @returns {boolean}
+ */
+function isTLSSocket(socket) {
+  return socket instanceof tls.TLSSocket;
+}
+
+/**
+ * Gets TLS connection info from a socket.
+ * @param {net.Socket|tls.TLSSocket} socket
+ * @returns {object|null} TLS info or null if not TLS
+ */
+function getTLSInfo(socket) {
+  if (!isTLSSocket(socket)) return null;
+
+  const tlsSocket = socket;
+  return {
+    encrypted: true,
+    protocol: tlsSocket.getProtocol(),
+    cipher: tlsSocket.getCipher(),
+    authorized: tlsSocket.authorized,
+    authorizationError: tlsSocket.authorizationError,
+  };
+}
+
+module.exports = {
+  createServerTransport,
+  validateTlsConfig,
+  isTLSSocket,
+  getTLSInfo,
+};