refactor: switch server API to command-based architecture

- Add handleCommand hook for server-side command dispatch in handlePacket
- Thread serverOptions (handleCommand, encoding) through createServer → Server → ConnectionConfig → Connection
- Add Query.fromPacket() for server-side COM_QUERY deserialization
- Make Handshake packet support configurable getSalt and authPluginName
- Simplify HandshakeResponse to accept pre-calculated authToken
- Use _serverEncoding getter for server write helpers (writeColumns, writeOk, etc.)
- Bump sequenceId by 1 on server-side command start
- Emit auth errors to connection instead of throwing

Author: sidorares

index.js

@@ -27,9 +27,19 @@ exports.Pool = Pool;
 
 exports.PoolCluster = PoolCluster;
 
-exports.createServer = function (handler) {
+exports.createServer = function (opts = {}) {
+  let handler;
+  if (typeof opts === 'function') {
+    handler = opts;
+    opts = {};
+  } else {
+    handler = opts.onConnection;
+  }
   const Server = require('./lib/server.js');
-  const s = new Server();
+  const s = new Server({
+    handleCommand: opts.handleCommand,
+    encoding: opts.encoding || 'cesu8',
+  });
   if (handler) {
     s.on('connection', handler);
   }

lib/base/connection.js

@@ -515,14 +515,20 @@ class BaseConnection extends EventEmitter {
         );
       }
     }
+    if (
+      !this._command &&
+      this.config.isServer &&
+      this.config.serverOptions?.handleCommand
+    ) {
+      const commandCode = packet.peekByte();
+      this._command = this.config.serverOptions.handleCommand(commandCode);
+    }
     if (!this._command) {
       const marker = packet.peekByte();
-      // If it's an Err Packet, we should use it.
       if (marker === 0xff) {
         const error = Packets.Error.fromPacket(packet);
         this.protocolError(error.message, error.code);
       } else {
-        // Otherwise, it means it's some other unexpected packet.
         this.protocolError(
           'Unexpected packet while no commands in the queue',
           'PROTOCOL_UNEXPECTED_PACKET'
@@ -1016,27 +1022,31 @@ class BaseConnection extends EventEmitter {
   // ===================================
   // outgoing server connection methods
   // ===================================
+
+  get _serverEncoding() {
+    return (
+      this.config.serverOptions?.encoding ||
+      (this.serverConfig && this.serverConfig.encoding) ||
+      'cesu8'
+    );
+  }
+
   writeColumns(columns) {
     this.writePacket(Packets.ResultSetHeader.toPacket(columns.length));
     columns.forEach((column) => {
       this.writePacket(
-        Packets.ColumnDefinition.toPacket(column, this.serverConfig.encoding)
+        Packets.ColumnDefinition.toPacket(column, this._serverEncoding)
       );
     });
     this.writeEof();
   }
 
-  // row is array of columns, not hash
   writeTextRow(column) {
-    this.writePacket(
-      Packets.TextRow.toPacket(column, this.serverConfig.encoding)
-    );
+    this.writePacket(Packets.TextRow.toPacket(column, this._serverEncoding));
   }
 
   writeBinaryRow(column) {
-    this.writePacket(
-      Packets.BinaryRow.toPacket(column, this.serverConfig.encoding)
-    );
+    this.writePacket(Packets.BinaryRow.toPacket(column, this._serverEncoding));
   }
 
   writeTextResult(rows, columns, binary = false) {
@@ -1061,13 +1071,11 @@ class BaseConnection extends EventEmitter {
     if (!args) {
       args = { affectedRows: 0 };
     }
-    this.writePacket(Packets.OK.toPacket(args, this.serverConfig.encoding));
+    this.writePacket(Packets.OK.toPacket(args, this._serverEncoding));
   }
 
   writeError(args) {
-    // if we want to send error before initial hello was sent, use default encoding
-    const encoding = this.serverConfig ? this.serverConfig.encoding : 'cesu8';
-    this.writePacket(Packets.Error.toPacket(args, encoding));
+    this.writePacket(Packets.Error.toPacket(args, this._serverEncoding));
   }
 
   serverHandshake(args) {

lib/commands/auth_switch.js

@@ -96,9 +96,11 @@ function authSwitchRequest(packet, connection, command) {
 
   const authPlugin = getAuthPlugin(pluginName, connection);
   if (!authPlugin) {
-    throw new Error(
-      `Server requests authentication using unknown plugin ${pluginName}. See ${'TODO: add plugins doco here'} on how to configure or author authentication plugins.`
+    const err = new Error(
+      `Server requests authentication using unknown plugin ${pluginName}.`
     );
+    connection.emit('error', err);
+    return;
   }
   connection._authPlugin = authPlugin({ connection, command });
   Promise.resolve(connection._authPlugin(pluginData))

lib/commands/client_handshake.js

@@ -14,6 +14,10 @@ const Command = require('./command.js');
 const Packets = require('../packets/index.js');
 const ClientConstants = require('../constants/client.js');
 const CharsetToEncoding = require('../constants/charset_encodings.js');
+
+// TODO: refactor to use plugins
+// need to coordinate with ChangeUser command,
+// currently it uses sync calculateNativePasswordAuthToken method from here
 const auth41 = require('../auth_41.js');
 const { getAuthPlugin } = require('./auth_switch.js');
 const {
@@ -60,27 +64,16 @@ class ClientHandshake extends Command {
     }
     this.user = connection.config.user;
     this.password = connection.config.password;
-    // "password1" is an alias to the original "password" value
-    // to make it easier to integrate multi-factor authentication
     this.password1 = connection.config.password;
-    // "password2" and "password3" are the 2nd and 3rd factor authentication
-    // passwords, which can be undefined depending on the authentication
-    // plugin being used
     this.password2 = connection.config.password2;
     this.password3 = connection.config.password3;
     this.passwordSha1 = connection.config.passwordSha1;
-    this.database = connection.config.database;
     this.authPluginName = this.handshake.authPluginName;
 
-    // Optimization: Try to use the server's preferred authentication method
-    // to avoid an unnecessary auth switch roundtrip
     const serverAuthMethod = this.handshake.authPluginName;
     const isSecureConnection =
       connection.config.ssl || connection.config.socketPath;
 
-    // Combine auth plugin data for easier handling
-    // Note: authPluginData2 can include a trailing NUL byte when PLUGIN_AUTH is set
-    // We must ensure exactly 20 bytes for the scramble
     const authPluginData =
       this.handshake.authPluginData1 && this.handshake.authPluginData2
         ? Buffer.concat([
@@ -89,8 +82,6 @@ class ClientHandshake extends Command {
           ]).slice(0, 20)
         : Buffer.alloc(20);
 
-    // Check if user has custom auth plugin or legacy handler for the server-advertised method
-    // If so, we must not bypass the auth switch flow with our built-in implementation
     const hasCustomAuthPlugin =
       connection.config.authPlugins &&
       Object.prototype.hasOwnProperty.call(
@@ -100,8 +91,6 @@ class ClientHandshake extends Command {
     const hasLegacyAuthSwitchHandler =
       typeof connection.config.authSwitchHandler === 'function';
 
-    // Determine which auth method to use
-    // Try to use server's preferred method if we can, otherwise fallback to native
     const canUseDirectAuth =
       !hasCustomAuthPlugin &&
       !hasLegacyAuthSwitchHandler &&
@@ -113,7 +102,6 @@ class ClientHandshake extends Command {
       ? serverAuthMethod
       : 'mysql_native_password';
 
-    // Calculate the auth token for the chosen method
     const authToken = this.calculateAuthToken(
       clientAuthMethod,
       this.password,
@@ -144,9 +132,6 @@ class ClientHandshake extends Command {
     });
     connection.writePacket(handshakeResponse.toPacket());
 
-    // If we used a non-native auth method in the initial handshake response,
-    // we need to prepare for potential AuthMoreData packets by creating
-    // the appropriate auth plugin instance
     if (clientAuthMethod !== 'mysql_native_password') {
       this.initializeAuthPlugin(clientAuthMethod, authPluginData, connection);
     }

lib/commands/command.js

@@ -24,6 +24,9 @@ class Command extends EventEmitter {
     if (!this.next) {
       this.next = this.start;
       connection._resetSequenceId();
+      if (connection.config.isServer) {
+        connection._bumpSequenceId(1);
+      }
     }
     if (packet && packet.isError()) {
       const err = packet.asError(connection.clientEncoding);

lib/commands/server_handshake.js

@@ -28,7 +28,7 @@ class ServerHandshake extends Command {
         connection.emit('error', new Error('Error generating random bytes'));
         return;
       }
-      connection.writePacket(serverHelloPacket.toPacket(0));
+      connection.writePacket(serverHelloPacket.toPacket(10));
     });
     return ServerHandshake.prototype.readClientReply;
   }
@@ -55,6 +55,7 @@ class ServerHandshake extends Command {
           // if (err)
           if (!mysqlError) {
             connection.writeOk();
+            connection.sequenceId = 0;
           } else {
             // TODO create constants / errorToCode
             // 1045 = ER_ACCESS_DENIED_ERROR

lib/connection_config.js

@@ -70,6 +70,7 @@ const validOptions = {
   waitForConnections: 1,
   jsonStrings: 1,
   gracefulEnd: 1,
+  serverOptions: 1,
 };
 
 class ConnectionConfig {
@@ -94,6 +95,7 @@ class ConnectionConfig {
       }
     }
     this.isServer = options.isServer;
+    this.serverOptions = options.serverOptions;
     this.stream = options.stream;
     this.host = options.host || 'localhost';
     this.port =

lib/packets/handshake.js

@@ -1,10 +1,22 @@
 'use strict';
 
+const crypto = require('crypto');
 const Packet = require('../packets/packet');
 const ClientConstants = require('../constants/client.js');
 
 // https://dev.mysql.com/doc/internals/en/connection-phase-packets.html#packet-Protocol::Handshake
 
+const getSalt = () =>
+  new Promise((accept, reject) => {
+    crypto.randomBytes(20, (err, data) => {
+      if (err) {
+        reject(err);
+        return;
+      }
+      accept(data);
+    });
+  });
+
 class Handshake {
   constructor(args) {
     this.protocolVersion = args.protocolVersion;
@@ -15,25 +27,22 @@ class Handshake {
     this.authPluginData2 = args.authPluginData2;
     this.characterSet = args.characterSet;
     this.statusFlags = args.statusFlags;
-    this.authPluginName = args.authPluginName;
+    this.authPluginName = args.authPluginName || 'mysql_native_password';
+    this.getSalt = args.getSalt || getSalt;
   }
 
   setScrambleData(cb) {
-    require('crypto').randomBytes(20, (err, data) => {
-      if (err) {
-        cb(err);
-        return;
-      }
-      this.authPluginData1 = data.slice(0, 8);
-      this.authPluginData2 = data.slice(8, 20);
+    this.getSalt().then((salt) => {
+      this.authPluginData1 = salt.slice(0, 8);
+      this.authPluginData2 = salt.slice(8, 20);
       cb();
     });
   }
 
-  toPacket(sequenceId) {
+  toPacket() {
     const length = 68 + Buffer.byteLength(this.serverVersion, 'utf8');
     const buffer = Buffer.alloc(length + 4, 0); // zero fill, 10 bytes filler later needs to contain zeros
-    const packet = new Packet(sequenceId, buffer, 0, length + 4);
+    const packet = new Packet(0, buffer, 0, length + 4);
     packet.offset = 4;
     packet.writeInt8(this.protocolVersion);
     packet.writeString(this.serverVersion, 'cesu8');
@@ -51,7 +60,7 @@ class Handshake {
     packet.skip(10);
     packet.writeBuffer(this.authPluginData2);
     packet.writeInt8(0);
-    packet.writeString('mysql_native_password', 'latin1');
+    packet.writeString(this.authPluginName, 'latin1');
     packet.writeInt8(0);
     return packet;
   }

lib/packets/handshake_response.js

@@ -4,59 +4,14 @@ const ClientConstants = require('../constants/client.js');
 const CharsetToEncoding = require('../constants/charset_encodings.js');
 const Packet = require('../packets/packet.js');
 
-const auth41 = require('../auth_41.js');
-
 class HandshakeResponse {
   constructor(handshake) {
     this.user = handshake.user || '';
     this.database = handshake.database || '';
-    this.password = handshake.password || '';
-    this.passwordSha1 = handshake.passwordSha1;
-    this.authPluginData1 = handshake.authPluginData1;
-    this.authPluginData2 = handshake.authPluginData2;
     this.compress = handshake.compress;
     this.clientFlags = handshake.flags;
-
-    // Accept pre-calculated authToken and authPluginName from caller
-    // This allows the caller to optimize by using the server's preferred auth method
-    if (
-      handshake.authToken !== undefined &&
-      handshake.authPluginName !== undefined
-    ) {
-      // Validate types to fail fast with clear errors
-      if (!Buffer.isBuffer(handshake.authToken)) {
-        throw new TypeError(
-          'HandshakeResponse authToken must be a Buffer when provided'
-        );
-      }
-      if (typeof handshake.authPluginName !== 'string') {
-        throw new TypeError(
-          'HandshakeResponse authPluginName must be a string when provided'
-        );
-      }
-      this.authToken = handshake.authToken;
-      this.authPluginName = handshake.authPluginName;
-    } else {
-      // Fallback to legacy behavior: calculate mysql_native_password token
-      // TODO: pre-4.1 auth support
-      let authToken;
-      if (this.passwordSha1) {
-        authToken = auth41.calculateTokenFromPasswordSha(
-          this.passwordSha1,
-          this.authPluginData1,
-          this.authPluginData2
-        );
-      } else {
-        authToken = auth41.calculateToken(
-          this.password,
-          this.authPluginData1,
-          this.authPluginData2
-        );
-      }
-      this.authToken = authToken;
-      this.authPluginName = 'mysql_native_password';
-    }
-
+    this.authToken = handshake.authToken;
+    this.authPluginName = handshake.authPluginName;
     this.charsetNumber = handshake.charsetNumber;
     this.encoding = CharsetToEncoding[handshake.charsetNumber];
     this.connectAttributes = handshake.connectAttributes;

lib/packets/query.js

@@ -97,6 +97,15 @@ class Query {
     const p = this.serializeToBuffer(Packet.MockBuffer());
     return this.serializeToBuffer(Buffer.allocUnsafe(p.offset));
   }
+
+  static fromPacket(packet, encoding) {
+    const _commandCode = packet.readInt8();
+    if (_commandCode !== CommandCode.QUERY) {
+      throw new Error('Incorrect command code for Query packet');
+    }
+    const query = packet.readString(undefined, encoding);
+    return new Query(query);
+  }
 }
 
 module.exports = Query;