local-development-gateway 0.1.3 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 10a939f848cae2b9e243772bb0b71e55f9f4ef7db51df904dbc44dceda981b0f
-  data.tar.gz: 0fe2303e0a7452356971343a371a73d897550d2461502bafba85ba81beb8bcba
+  metadata.gz: 8baffa29acc52adfcc3112cacc9be936b24528915f86fbc94c323df081e05fd5
+  data.tar.gz: 4ab5156e3dc8dae143345b3c58271be2afd4b3485fb92c6bfd18153dd1958734
 SHA512:
-  metadata.gz: 9a5b33aceca3f70ae6d50fe53dd6a398badbde7b2f7869a2099507bd361308843cc8189924cae4adb0c8203afe189c62a002ed694d73cb0efe9bc8089edab92e
-  data.tar.gz: '086a30b8f018bf0fd4ce44d410ba5dc23cbb4923d28afd225df171a1c9453a2a3f4cf2a24f8c2a4ed75fb3587f00aa9022cf03c4556a1e73ffc98f269936e95b'
+  metadata.gz: 8ed0938cfb210bda2c320f6c481af5ddabf9f32d8f04fcac7ac94f60bbc9df8da98fe71f7929581d54ab5a20b648c339b92cd78f799b50fb74f3300e64997e0c
+  data.tar.gz: b1acdaefc1c2b69b1e101fb5516ee8de7de866e9d9b1d11bd2390d14a860204a869ca8d90a10123a9b304b954fb03297c26b80482743105bee5a53f3bad06c22

data/README.md

@@ -66,7 +66,7 @@ Consuming projects do not need a gateway checkout. Add the released gem to
 their bundle and pin the compatible minor version:
 
 ```ruby
-gem "local-development-gateway", "~> 0.1"
+gem "local-development-gateway", "~> 0.2"
 ```
 
 Published gem: [`local-development-gateway`](https://rubygems.org/gems/local-development-gateway)
@@ -83,7 +83,7 @@ bundle exec local-development-gateway down
 
 `local-development-gateway` uses the installed asset path, the
 `local-gateway` Compose project and network labels, and the pinned minimum Ruby
-version declared by the gem. The `~> 0.1` constraint follows the consuming
+version declared by the gem. The `~> 0.2` constraint follows the consuming
 project's published Gemfile.
 The repository's `bin/dev` is only a thin wrapper around this executable API.
 
@@ -106,6 +106,65 @@ command that must not start a missing gateway, pass
 `ensure_running: false`; the block still runs and unused-gateway cleanup is
 attempted.
 
+## Worktree database services
+
+The gateway includes protocol drivers for encrypted SQL Server and PostgreSQL
+connections. No host agent, DNS server, administrator privileges, or
+`/etc/hosts` changes are required.
+
+A participating project only joins its existing database service to
+`local-gateway` and adds three labels:
+
+```yaml
+services:
+  db:
+    networks:
+      - default
+      - local-gateway
+    labels:
+      - "local-gateway.tcp.driver=sql_server"
+      - "local-gateway.tcp.hostname=db.${GATEWAY_HOSTNAME:-wrap.localhost}"
+      - "local-gateway.tcp.port=1433"
+
+networks:
+  local-gateway:
+    external: true
+    name: local-gateway
+```
+
+For a worktree whose `GATEWAY_HOSTNAME` is `issue-567.wrap.localhost`, DBeaver
+connects to `db.issue-567.wrap.localhost` on the driver's standard port:
+
+| Driver label | Host port | Client requirement |
+| --- | ---: | --- |
+| `sql_server` | `1433` | Encryption enabled and **Trust server certificate** selected |
+| `postgresql` | `5432` | SSL mode `require` |
+
+Use the database container's actual internal port in
+`local-gateway.tcp.port`; it does not need to match the host listener.
+
+Remove the database's host `ports` publication when using the gateway; the shared
+router owns `127.0.0.1:1433` and `127.0.0.1:5432`. Keep the `default` network so
+application and test containers still connect directly to `db` on its internal
+port, without TLS or a host-published port. A project not using the gateway must
+select its own explicit port-publishing fallback.
+
+All `.localhost` names resolve to loopback. The gateway publishes loopback-only
+listeners, discovers labelled containers through Docker, and uses the database
+protocol's encrypted handshake to select the hostname-labelled container.
+Container replacements and stopped routes require no consumer lifecycle code
+or cleanup.
+
+SQL Server encryption remains end to end through the router. PostgreSQL TLS
+terminates at the gateway; the backend stream is plaintext on the private Docker
+network. New PostgreSQL sessions require TLS and SNI, but query cancellation
+does not: the gateway substitutes a session-specific cancellation identity and
+routes ordinary `psql` and JDBC cancellation packets to that session's backend.
+Closed sessions lose their cancellation mapping. See
+[`docs/architecture/local-tcp-routing.md`](docs/architecture/local-tcp-routing.md)
+for the complete contract and security boundary, including the reason for
+retaining cancellation-aware PostgreSQL routing despite Traefik's STARTTLS support.
+
 ## Development checks
 
 Install the locked development tools with `bundle install`. Run the Ruby
@@ -116,10 +175,19 @@ bundle exec ruby "$(bundle show syntax_tree)/exe/stree" check \
   Gemfile \
   Rakefile \
   lib/local_development_gateway.rb \
+  lib/local_development_gateway/database_router.rb \
+  lib/local_development_gateway/database_router/*.rb \
+  lib/local_development_gateway/database_router/drivers/*.rb \
+  lib/local_development_gateway/database_router/postgre_sql/*.rb \
+  lib/local_development_gateway/database_router/tds/*.rb \
   lib/local_development_gateway/version.rb \
   bin/dev \
   bin/local-development-gateway \
-  test/local_development_gateway_test.rb
+  test/*.rb \
+  test/database_router/*.rb \
+  test/database_router/drivers/*.rb \
+  test/database_router/postgre_sql/*.rb \
+  test/database_router/tds/*.rb
 rake test
 ```
 
@@ -194,3 +262,16 @@ It mounts the Docker socket so it can discover labelled containers. A read-only
 | Generated hostname returns `404` | Confirm the web container has the route labels and is attached to `local-gateway`. |
 | A project uses normal ports unexpectedly | Confirm the gateway container is running and has `local-gateway=true`. |
 | Authentication rejects the callback | Confirm the generated hostname matches the allowed wildcard callback pattern. |
+
+## Release 0.2.1
+
+- PostgreSQL query cancellation works across concurrent worktrees, including
+  plaintext cancellation from `psql` and JDBC and encrypted cancellation.
+  Session-specific identities prevent backend key collisions and expire when
+  their session closes.
+- Invalid database labels and duplicate hostname identities reject only the
+  affected routes, leaving unrelated worktrees and database drivers available.
+- SQL Server negotiation can fall back from a stalled backend within the
+  shared handshake deadline.
+- PostgreSQL STARTTLS support in Traefik is documented accurately. The gateway
+  retains cancellation-aware session routing without changing consumer labels.

data/docker-compose.yml

@@ -22,6 +22,37 @@ services:
     networks:
       - local-gateway
 
+  database-router:
+    image: ruby:3.4.7-alpine
+    command:
+      - ruby
+      - -I/app/lib
+      - -rlocal_development_gateway
+      - -e
+      - LocalDevelopmentGateway::DatabaseRouter.run
+    healthcheck:
+      test:
+        - CMD
+        - ruby
+        - -rsocket
+        - -e
+        - TCPSocket.new("127.0.0.1", 1433).close; TCPSocket.new("127.0.0.1", 5432).close
+      interval: 1s
+      timeout: 3s
+      retries: 30
+      start_period: 1s
+    labels:
+      local-gateway: "true"
+    ports:
+      - "127.0.0.1:1433:1433"
+      - "127.0.0.1:5432:5432"
+    restart: unless-stopped
+    volumes:
+      - ./lib:/app/lib:ro
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+    networks:
+      - local-gateway
+
 networks:
   local-gateway:
     name: local-gateway

data/lib/local_development_gateway/database_router/docker_api.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "json"
+require "socket"
+
+require "local_development_gateway/database_router/wire"
+
+module LocalDevelopmentGateway
+  class DatabaseRouter::DockerApi
+    MAX_RESPONSE_BYTES = 8 * 1024 * 1024
+    SOCKET_PATH = "/var/run/docker.sock"
+
+    def initialize(socket_path: SOCKET_PATH)
+      @socket_path = socket_path
+    end
+
+    def get(path)
+      socket = UNIXSocket.new(@socket_path)
+      socket.write(
+        "GET #{path} HTTP/1.1\r\nHost: docker\r\nConnection: close\r\n\r\n"
+      )
+      response =
+        DatabaseRouter::Wire.read_until_eof(
+          socket,
+          max_bytes: MAX_RESPONSE_BYTES,
+          deadline: DatabaseRouter::Wire.deadline
+        )
+      headers, body = response.split("\r\n\r\n", 2)
+      unless headers&.start_with?("HTTP/1.1 200", "HTTP/1.0 200")
+        raise Error,
+              "Docker API request failed: #{headers&.lines&.first&.strip}"
+      end
+
+      body = decode_chunks(body) if headers.downcase.include?(
+        "transfer-encoding: chunked"
+      )
+      JSON.parse(body)
+    ensure
+      socket&.close
+    end
+
+    private
+
+    def decode_chunks(body)
+      decoded = +""
+      loop do
+        line_end = body.index("\r\n")
+        raise Error, "Invalid chunked Docker API response" unless line_end
+
+        size = Integer(body.byteslice(0, line_end).split(";", 2).first, 16)
+        body = body.byteslice(line_end + 2..)
+        break if size.zero?
+        unless body.bytesize >= size + 2 && body.byteslice(size, 2) == "\r\n"
+          raise Error, "Invalid chunked Docker API response"
+        end
+
+        decoded << body.byteslice(0, size)
+        body = body.byteslice(size + 2..)
+      end
+      decoded
+    rescue ArgumentError, TypeError
+      raise Error, "Invalid chunked Docker API response"
+    end
+  end
+end

data/lib/local_development_gateway/database_router/docker_routes.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "local_development_gateway/database_router/docker_api"
+
+module LocalDevelopmentGateway
+  class DatabaseRouter::DockerRoutes
+    NETWORK_NAME = "local-gateway"
+    HOSTNAME_LABEL = "local-gateway.tcp.hostname"
+    PORT_LABEL = "local-gateway.tcp.port"
+    DRIVER_LABEL = "local-gateway.tcp.driver"
+    HOSTNAME_PATTERN = /\A(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)+localhost\z/
+
+    def initialize(client: DatabaseRouter::DockerApi.new)
+      @client = client
+    end
+
+    def call
+      routes =
+        @client
+          .get("/containers/json")
+          .filter_map do |container|
+            begin
+              route(container)
+            rescue Error => error
+              warn error.message
+              nil
+            end
+          end
+      identities = routes.group_by { |route| [route.driver, route.hostname] }
+      identities.each do |identity, matches|
+        next if matches.length == 1
+
+        warn "Duplicate labelled database hostname: #{identity.join(" ")}"
+      end
+
+      routes
+        .reject do |route|
+          identities.fetch([route.driver, route.hostname]).length > 1
+        end
+        .sort_by { |route| [route.driver, route.hostname] }
+    end
+
+    private
+
+    def route(container)
+      target_address =
+        container.dig("NetworkSettings", "Networks", NETWORK_NAME, "IPAddress")
+      return if target_address.nil? || target_address.empty?
+
+      labels = container.fetch("Labels")
+      driver = labels[DRIVER_LABEL]
+      hostname = labels[HOSTNAME_LABEL]
+      port = labels[PORT_LABEL]
+      values = [driver, hostname, port]
+      return if values.all?(&:nil?)
+      raise Error, "Incomplete labelled database route" if values.any?(&:nil?)
+
+      unless DatabaseRouter.drivers.any? { |candidate|
+               candidate.name == driver
+             }
+        raise Error, "Unsupported database driver: #{driver}"
+      end
+      unless HOSTNAME_PATTERN.match?(hostname)
+        raise Error, "Invalid labelled database hostname: #{hostname}"
+      end
+
+      port = Integer(port, 10)
+      unless (1..65_535).cover?(port)
+        raise Error, "Invalid labelled database port: #{port}"
+      end
+
+      DatabaseRouter::Route.new(
+        driver: driver,
+        hostname: hostname,
+        port: port,
+        target_address: target_address
+      )
+    rescue KeyError
+      raise Error, "Incomplete labelled database route"
+    rescue ArgumentError, TypeError
+      raise Error, "Invalid labelled database port: #{port}"
+    end
+  end
+end

data/lib/local_development_gateway/database_router/drivers/postgre_sql_certificate.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module LocalDevelopmentGateway
+  module DatabaseRouter::Drivers
+    class PostgreSqlCertificate
+      def initialize
+        @key = OpenSSL::PKey::EC.generate("prime256v1")
+        @certificate = OpenSSL::X509::Certificate.new
+        @certificate.version = 2
+        @certificate.serial = 1
+        @certificate.subject =
+          OpenSSL::X509::Name.parse("/CN=local-development-gateway")
+        @certificate.issuer = @certificate.subject
+        @certificate.public_key = @key
+        @certificate.not_before = Time.now - 60
+        @certificate.not_after = Time.now + (10 * 365 * 24 * 60 * 60)
+        extensions = OpenSSL::X509::ExtensionFactory.new
+        extensions.subject_certificate = @certificate
+        extensions.issuer_certificate = @certificate
+        @certificate.add_extension(
+          extensions.create_extension("basicConstraints", "CA:FALSE", true)
+        )
+        @certificate.add_extension(
+          extensions.create_extension("keyUsage", "digitalSignature", true)
+        )
+        @certificate.add_extension(
+          extensions.create_extension("extendedKeyUsage", "serverAuth")
+        )
+        @certificate.sign(@key, OpenSSL::Digest::SHA256.new)
+      end
+
+      def context(&servername_callback)
+        context = OpenSSL::SSL::SSLContext.new
+        context.cert = @certificate
+        context.key = @key
+        context.min_version = OpenSSL::SSL::TLS1_2_VERSION
+        context.servername_cb = servername_callback
+        context
+      end
+    end
+  end
+end

data/lib/local_development_gateway/database_router/drivers/postgre_sql_driver.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+require "local_development_gateway/database_router/wire"
+require "local_development_gateway/database_router/drivers/postgre_sql_certificate"
+require "local_development_gateway/database_router/postgre_sql/session"
+
+module LocalDevelopmentGateway
+  module DatabaseRouter::Drivers
+    class PostgreSqlDriver
+      NAME = "postgresql"
+      LISTEN_PORT = 5432
+      SSL_REQUEST = [8, 80_877_103].pack("NN").freeze
+      CANCEL_REQUEST = [16, 80_877_102].pack("NN").freeze
+
+      def initialize(
+        certificate: PostgreSqlCertificate.new,
+        cancellations: DatabaseRouter::PostgreSql::CancellationRoutes.new
+      )
+        @certificate = certificate
+        @cancellations = cancellations
+      end
+
+      def name
+        NAME
+      end
+
+      def listen_port
+        LISTEN_PORT
+      end
+
+      def connect(client, routes:, connector:)
+        deadline = DatabaseRouter::Wire.deadline
+        request =
+          DatabaseRouter::Wire.read_exactly(client, 8, deadline: deadline)
+        if cancel_request?(request)
+          cancel(client, connector, deadline)
+          return
+        end
+        raise Error, "PostgreSQL SSL is required" unless request == SSL_REQUEST
+
+        client.write("S")
+        hostname = nil
+        context =
+          @certificate.context do |_socket, name|
+            hostname = name&.downcase
+            nil
+          end
+        tls = OpenSSL::SSL::SSLSocket.new(client, context)
+        tls.sync_close = true
+        DatabaseRouter::Wire.accept_tls(tls, deadline: deadline)
+
+        startup = DatabaseRouter::Wire.read_exactly(tls, 8, deadline: deadline)
+        if cancel_request?(startup)
+          cancel(tls, connector, deadline)
+          tls.close
+          return
+        end
+
+        length, version = startup.unpack("NN")
+        unless length >= 9 && (version >> 16) == 3
+          raise Error, "Unsupported PostgreSQL startup request"
+        end
+
+        unless hostname
+          raise Error, "PostgreSQL TLS ClientHello does not contain SNI"
+        end
+
+        selected = routes.call.find { |route| route.hostname == hostname }
+        raise Error, "No PostgreSQL route for #{hostname}" unless selected
+
+        target = connector.call(selected, deadline: deadline)
+        target.write(startup)
+        DatabaseRouter::Connection.new(
+          source: tls,
+          target: target,
+          route: selected
+        )
+      rescue StandardError
+        tls&.close
+        target&.close
+        raise
+      end
+
+      def forward(connection)
+        session = DatabaseRouter::PostgreSql::Session.new(@cancellations)
+        DatabaseRouter::Wire.proxy(
+          connection.source,
+          connection.target
+        ) do |backend, client|
+          session.forward_response(backend, client, connection.route)
+        end
+      end
+
+      private
+
+      def cancel_request?(header)
+        return false unless header.byteslice(4, 4).unpack1("N") == 80_877_102
+        unless header == CANCEL_REQUEST
+          raise Error, "Invalid PostgreSQL cancellation length"
+        end
+
+        true
+      end
+
+      def cancel(client, connector, deadline)
+        identity =
+          DatabaseRouter::Wire.read_exactly(client, 8, deadline: deadline)
+        destination = @cancellations.resolve(identity)
+        return unless destination
+
+        target = connector.call(destination.route, deadline: deadline)
+        packet = [destination.backend_key.bytesize + 8, 80_877_102].pack("NN")
+        target.write(packet + destination.backend_key)
+        DatabaseRouter::Wire.read_until_eof(
+          target,
+          max_bytes: 0,
+          deadline: deadline
+        )
+      ensure
+        target&.close
+      end
+    end
+  end
+end

data/lib/local_development_gateway/database_router/drivers/sql_server_driver.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "local_development_gateway/database_router/tds/message"
+require "local_development_gateway/database_router/tds/tls_client_hello"
+
+module LocalDevelopmentGateway
+  module DatabaseRouter::Drivers
+    class SqlServerDriver
+      NEGOTIATION_ATTEMPT_TIMEOUT = 1
+
+      NAME = "sql_server"
+      LISTEN_PORT = 1433
+
+      def name
+        NAME
+      end
+
+      def listen_port
+        LISTEN_PORT
+      end
+
+      def connect(client, routes:, connector:)
+        deadline = DatabaseRouter::Wire.deadline
+        prelogin = DatabaseRouter::Tds::Message.read(client, deadline: deadline)
+        routes = routes.call
+        if routes.empty?
+          raise Error, "No labelled sql_server routes are available"
+        end
+        provisional, target, response =
+          negotiate(routes, prelogin, connector, deadline)
+        DatabaseRouter::Tds::Message.write(client, response)
+
+        hostname, messages = read_client_hello(client, deadline)
+        selected = routes.find { |route| route.hostname == hostname }
+        raise Error, "No SQL Server route for #{hostname}" unless selected
+
+        if selected != provisional
+          target.close
+          target = connector.call(selected, deadline: deadline)
+          DatabaseRouter::Tds::Message.write(target, prelogin)
+          DatabaseRouter::Tds::Message.read(target, deadline: deadline)
+        end
+
+        messages.each do |message|
+          DatabaseRouter::Tds::Message.write(target, message)
+        end
+        DatabaseRouter::Connection.new(
+          source: client,
+          target: target,
+          route: selected
+        )
+      rescue StandardError
+        target&.close
+        raise
+      end
+
+      def forward(connection)
+        DatabaseRouter::Wire.proxy(connection.source, connection.target)
+      end
+
+      private
+
+      def negotiate(routes, prelogin, connector, deadline)
+        routes.each do |route|
+          remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          break unless remaining.positive?
+
+          attempt_deadline = [
+            deadline,
+            Process.clock_gettime(Process::CLOCK_MONOTONIC) +
+              NEGOTIATION_ATTEMPT_TIMEOUT
+          ].min
+          target = connector.call(route, deadline: attempt_deadline)
+          DatabaseRouter::Tds::Message.write(target, prelogin)
+          return [
+            route,
+            target,
+            DatabaseRouter::Tds::Message.read(
+              target,
+              deadline: attempt_deadline
+            )
+          ]
+        rescue Error, EOFError, IOError, SystemCallError
+          target&.close
+        end
+        raise Error, "No labelled SQL Server backends are reachable"
+      end
+
+      def read_client_hello(client, deadline)
+        hello = DatabaseRouter::Tds::TlsClientHello.new
+        messages = []
+        loop do
+          message =
+            DatabaseRouter::Tds::Message.read(client, deadline: deadline)
+          messages << message
+          hostname = hello.append(message.payload)
+          return hostname, messages if hostname
+        end
+      end
+    end
+  end
+end

data/lib/local_development_gateway/database_router/postgre_sql/cancellation_routes.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module LocalDevelopmentGateway
+  module DatabaseRouter::PostgreSql
+    class CancellationRoutes
+      Destination = Data.define(:route, :backend_key)
+
+      def initialize
+        @destinations = {}
+        @mutex = Mutex.new
+      end
+
+      def register(route, backend_key)
+        @mutex.synchronize do
+          identity = new_identity
+          identity = new_identity while @destinations.key?(identity)
+
+          identity.freeze
+          @destinations[identity] = Destination.new(
+            route: route,
+            backend_key: backend_key.dup.freeze
+          )
+          identity
+        end
+      end
+
+      def resolve(identity)
+        @mutex.synchronize { @destinations[identity] }
+      end
+
+      def remove(identity)
+        @mutex.synchronize { @destinations.delete(identity) }
+      end
+
+      private
+
+      def new_identity
+        identity = SecureRandom.random_bytes(8)
+        identity.setbyte(0, identity.getbyte(0) & 0x7f)
+        identity.setbyte(3, 1) if identity.unpack1("N").zero?
+        identity
+      end
+    end
+  end
+end

data/lib/local_development_gateway/database_router/postgre_sql/session.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "local_development_gateway/database_router/postgre_sql/cancellation_routes"
+
+module LocalDevelopmentGateway
+  class DatabaseRouter::PostgreSql::Session
+    MAX_BACKEND_KEY_BYTES = 260
+
+    def initialize(cancellations)
+      @cancellations = cancellations
+    end
+
+    def forward_response(backend, client, route)
+      identity = nil
+      loop do
+        header = backend.read(5)
+        raise EOFError unless header&.bytesize == 5
+
+        payload_length = header.byteslice(1, 4).unpack1("N") - 4
+        if payload_length.negative?
+          raise Error, "Invalid PostgreSQL message length"
+        end
+
+        if header.getbyte(0) == "K".ord
+          unless (8..MAX_BACKEND_KEY_BYTES).cover?(payload_length)
+            raise Error, "Invalid PostgreSQL backend key length"
+          end
+
+          backend_key = backend.read(payload_length)
+          raise EOFError unless backend_key&.bytesize == payload_length
+
+          identity = @cancellations.register(route, backend_key)
+          client.write("K" + [12].pack("N") + identity)
+          IO.copy_stream(backend, client)
+          return
+        end
+
+        client.write(header)
+        copied = IO.copy_stream(backend, client, payload_length)
+        raise EOFError unless copied == payload_length
+      end
+    ensure
+      @cancellations.remove(identity) if identity
+    end
+  end
+end

data/lib/local_development_gateway/database_router/tds/message.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "local_development_gateway/database_router/wire"
+
+module LocalDevelopmentGateway
+  module DatabaseRouter::Tds
+    class Message
+      MAX_BYTES = 1024 * 1024
+      MAX_PACKETS = 16
+      Packet = Data.define(:header, :payload)
+
+      attr_reader :packets
+
+      def self.read(io, deadline:)
+        packets = []
+        size = 0
+        loop do
+          if packets.length >= MAX_PACKETS
+            raise Error, "TDS message has too many packets"
+          end
+
+          header = DatabaseRouter::Wire.read_exactly(io, 8, deadline: deadline)
+          length = header.byteslice(2, 2).unpack1("n")
+          raise Error, "Invalid TDS packet length" if length < 8
+
+          size += length - 8
+          raise Error, "TDS message is too large" if size > MAX_BYTES
+
+          packets << Packet.new(
+            header: header,
+            payload:
+              DatabaseRouter::Wire.read_exactly(
+                io,
+                length - 8,
+                deadline: deadline
+              )
+          )
+          break if header.getbyte(1) & 1 == 1
+        end
+        new(packets)
+      end
+
+      def self.write(io, message)
+        message.packets.each do |packet|
+          io.write(packet.header, packet.payload)
+        end
+      end
+
+      def initialize(packets)
+        @packets = packets
+      end
+
+      def payload
+        packets.map(&:payload).join
+      end
+    end
+  end
+end

data/lib/local_development_gateway/database_router/tds/tls_byte_reader.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module LocalDevelopmentGateway
+  class DatabaseRouter::Tds::TlsByteReader
+    def initialize(bytes)
+      @bytes = bytes
+      @offset = 0
+    end
+
+    def empty?
+      @offset == @bytes.bytesize
+    end
+
+    def read(length)
+      if length.negative? || @offset + length > @bytes.bytesize
+        raise Error, "Invalid TLS ClientHello"
+      end
+
+      value = @bytes.byteslice(@offset, length)
+      @offset += length
+      value
+    end
+
+    def uint8
+      read(1).unpack1("C")
+    end
+
+    def uint16
+      read(2).unpack1("n")
+    end
+
+    def vector8
+      read(uint8)
+    end
+
+    def vector16
+      read(uint16)
+    end
+  end
+end

data/lib/local_development_gateway/database_router/tds/tls_client_hello.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "local_development_gateway/database_router/tds/tls_byte_reader"
+
+module LocalDevelopmentGateway
+  class DatabaseRouter::Tds::TlsClientHello
+    MAX_BYTES = 128 * 1024
+    MAX_RECORD_BYTES = (16 * 1024) + 2048
+
+    def initialize
+      @record_buffer = +""
+      @handshake = +""
+      @received = 0
+    end
+
+    def append(bytes)
+      @received += bytes.bytesize
+      raise Error, "TLS ClientHello is too large" if @received > MAX_BYTES
+
+      @record_buffer << bytes
+      consume_records
+      server_name if complete?
+    end
+
+    private
+
+    def consume_records
+      while @record_buffer.bytesize >= 5
+        content_type = @record_buffer.getbyte(0)
+        length = @record_buffer.byteslice(3, 2).unpack1("n")
+        raise Error, "Invalid TLS ClientHello record" unless content_type == 22
+        raise Error, "TLS record is too large" if length > MAX_RECORD_BYTES
+        break if @record_buffer.bytesize < length + 5
+
+        @handshake << @record_buffer.byteslice(5, length)
+        @record_buffer = @record_buffer.byteslice(length + 5..) || +""
+      end
+    end
+
+    def complete?
+      return false if @handshake.bytesize < 4
+      unless @handshake.getbyte(0) == 1
+        raise Error, "Expected a TLS ClientHello"
+      end
+
+      @handshake.bytesize >= 4 + uint24(@handshake, 1)
+    end
+
+    def server_name
+      length = uint24(@handshake, 1)
+      reader =
+        DatabaseRouter::Tds::TlsByteReader.new(@handshake.byteslice(4, length))
+      reader.read(2 + 32)
+      reader.vector8
+      reader.vector16
+      reader.vector8
+      extensions = DatabaseRouter::Tds::TlsByteReader.new(reader.vector16)
+      until extensions.empty?
+        type = extensions.uint16
+        data = extensions.vector16
+        next unless type.zero?
+
+        names =
+          DatabaseRouter::Tds::TlsByteReader.new(
+            DatabaseRouter::Tds::TlsByteReader.new(data).vector16
+          )
+        until names.empty?
+          name_type = names.uint8
+          name = names.vector16
+          if name_type.zero?
+            return name.force_encoding(Encoding::UTF_8).downcase
+          end
+        end
+      end
+      raise Error, "TLS ClientHello does not contain SNI"
+    end
+
+    def uint24(bytes, offset)
+      (bytes.getbyte(offset) << 16) | (bytes.getbyte(offset + 1) << 8) |
+        bytes.getbyte(offset + 2)
+    rescue NoMethodError
+      raise Error, "Invalid TLS ClientHello"
+    end
+  end
+end

data/lib/local_development_gateway/database_router/wire.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "socket"
+
+module LocalDevelopmentGateway
+  module DatabaseRouter::Wire
+    HANDSHAKE_TIMEOUT = 5
+
+    module_function
+
+    def deadline
+      Process.clock_gettime(Process::CLOCK_MONOTONIC) + HANDSHAKE_TIMEOUT
+    end
+
+    def read_exactly(io, length, deadline:)
+      bytes = +""
+      while bytes.bytesize < length
+        remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        raise Error, "Database handshake timed out" unless remaining.positive?
+
+        chunk = io.read_nonblock(length - bytes.bytesize, exception: false)
+        case chunk
+        when :wait_readable
+          wait(io, readable: true, deadline: deadline)
+        when :wait_writable
+          wait(io, readable: false, deadline: deadline)
+        when nil
+          raise EOFError
+        else
+          bytes << chunk
+        end
+      end
+      bytes
+    end
+
+    def proxy(client, target, &response)
+      upstream =
+        Thread.new do
+          IO.copy_stream(client, target)
+        rescue IOError, EOFError, OpenSSL::SSL::SSLError, SystemCallError
+          nil
+        ensure
+          close_write(target)
+        end
+      downstream =
+        Thread.new do
+          if response
+            response.call(target, client)
+          else
+            IO.copy_stream(target, client)
+          end
+        rescue IOError, EOFError, OpenSSL::SSL::SSLError, SystemCallError
+          nil
+        ensure
+          close_connection(client)
+          close_connection(target)
+        end
+      threads = [upstream, downstream]
+      threads.each { |thread| thread.report_on_exception = false }
+      threads.each(&:join)
+    ensure
+      close_connection(client)
+      close_connection(target)
+      threads&.each(&:join)
+    end
+
+    def close_write(io)
+      io.close_write unless io.closed?
+    rescue IOError, SystemCallError
+      nil
+    end
+
+    def close_connection(io)
+      socket = io.to_io
+      socket.shutdown(Socket::SHUT_RDWR) unless socket.closed?
+    rescue IOError, SystemCallError
+      nil
+    ensure
+      io.close unless io.closed?
+    end
+
+    def read_until_eof(io, max_bytes:, deadline:)
+      bytes = +""
+      loop do
+        wait(io, readable: true, deadline: deadline)
+        bytes << io.readpartial(16 * 1024)
+        raise Error, "Response is too large" if bytes.bytesize > max_bytes
+      end
+    rescue EOFError
+      bytes
+    end
+
+    def accept_tls(socket, deadline:)
+      loop do
+        case socket.accept_nonblock(exception: false)
+        when :wait_readable
+          wait(socket, readable: true, deadline: deadline)
+        when :wait_writable
+          wait(socket, readable: false, deadline: deadline)
+        else
+          return socket
+        end
+      end
+    rescue OpenSSL::SSL::SSLError => error
+      raise Error, "PostgreSQL TLS handshake failed: #{error.message}"
+    end
+
+    def wait(io, readable:, deadline:)
+      remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      ready =
+        remaining.positive? &&
+          IO.select(
+            readable ? [io] : nil,
+            readable ? nil : [io],
+            nil,
+            remaining
+          )
+      raise Error, "Database handshake timed out" unless ready
+    end
+  end
+end

data/lib/local_development_gateway/database_router.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "socket"
+
+module LocalDevelopmentGateway
+  class DatabaseRouter
+    CONNECT_TIMEOUT = 3
+    MAX_CONNECTIONS = 128
+    MAX_HANDSHAKES = 128
+    Route = Data.define(:driver, :hostname, :port, :target_address)
+    Connection = Data.define(:source, :target, :route)
+
+    def self.run
+      new.run
+    end
+
+    def self.drivers
+      @drivers ||= [
+        Drivers::SqlServerDriver.new,
+        Drivers::PostgreSqlDriver.new
+      ].freeze
+    end
+
+    def initialize(
+      routes: DockerRoutes.new,
+      drivers: self.class.drivers,
+      servers: nil,
+      max_connections: MAX_CONNECTIONS
+    )
+      @routes = routes
+      @drivers = drivers
+      @session_slots = SizedQueue.new(max_connections)
+      max_connections.times { @session_slots << true }
+      @servers =
+        servers ||
+          drivers.to_h do |driver|
+            [driver.name, TCPServer.new("0.0.0.0", driver.listen_port)]
+          end
+    end
+
+    def run
+      slots = SizedQueue.new(MAX_HANDSHAKES)
+      MAX_HANDSHAKES.times { slots << true }
+      @drivers
+        .map do |driver|
+          Thread.new do
+            server = @servers.fetch(driver.name)
+            loop do
+              client = server.accept
+              slots.pop
+              Thread.new(client) do |connection|
+                route(connection, driver, handshake_slots: slots)
+              end
+            end
+          end
+        end
+        .each(&:join)
+    end
+
+    def route(client, driver, handshake_slots: nil)
+      routes = -> do
+        @routes.call.select { |route| route.driver == driver.name }
+      end
+      connection =
+        driver.connect(client, routes: routes, connector: method(:connect))
+      handshake_slots&.push(true)
+      handshake_slots = nil
+      return unless connection
+
+      session_slot = @session_slots.pop(true)
+      driver.forward(connection)
+    rescue EOFError
+      nil
+    rescue ThreadError
+      warn "Database session limit reached"
+    rescue Error => error
+      warn error.message
+    rescue StandardError => error
+      warn error.full_message
+    ensure
+      handshake_slots&.push(true)
+      @session_slots << true if session_slot
+      connection&.source&.close
+      client&.close
+      connection&.target&.close
+    end
+
+    private
+
+    def connect(route, deadline:)
+      remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      raise Error, "Database handshake timed out" unless remaining.positive?
+
+      Socket.tcp(
+        route.target_address,
+        route.port,
+        connect_timeout: [CONNECT_TIMEOUT, remaining].min
+      )
+    end
+  end
+end
+
+require "local_development_gateway/database_router/docker_routes"
+require "local_development_gateway/database_router/drivers/sql_server_driver"
+require "local_development_gateway/database_router/drivers/postgre_sql_driver"

data/lib/local_development_gateway/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module LocalDevelopmentGateway
-  VERSION = "0.1.3"
+  VERSION = "0.2.1"
 end

data/lib/local_development_gateway.rb

@@ -1,13 +1,14 @@
 # frozen_string_literal: true
 
 require "open3"
-require_relative "local_development_gateway/version"
+require "local_development_gateway/version"
 
 module LocalDevelopmentGateway
   PROJECT_NAME = "local-gateway"
   NETWORK_NAME = "local-gateway"
-  SERVICE_NAME = "gateway"
+  SERVICE_NAMES = %w[gateway database-router].freeze
   GATEWAY_LABEL = "local-gateway"
+  OBSOLETE_SERVICE_NAMES = %w[dns tds-router].freeze
   ASSET_ROOT = File.expand_path("..", __dir__)
   COMPOSE_FILE = File.join(ASSET_ROOT, "docker-compose.yml")
   TRAEFIK_CONFIG_FILE = File.join(ASSET_ROOT, "config", "traefik.yml")
@@ -15,6 +16,8 @@ module LocalDevelopmentGateway
   class Error < StandardError
   end
 
+  require "local_development_gateway/database_router"
+
   class DockerError < Error
     attr_reader :command, :output
 
@@ -72,9 +75,12 @@ module LocalDevelopmentGateway
     alias start ensure_running
 
     def ready?
-      network_exists? &&
-        gateway_container_ids(status: "running").any? do |id|
-          healthy_container?(id)
+      network_exists? && obsolete_services_absent? &&
+        SERVICE_NAMES.all? do |service|
+          gateway_container_ids(
+            service: service,
+            status: "running"
+          ).any? { |id| healthy_container?(id) }
         end
     end
 
@@ -150,10 +156,13 @@ module LocalDevelopmentGateway
     end
 
     def gateway_exists?
-      network_exists? && !gateway_container_ids.empty?
+      network_exists? &&
+        SERVICE_NAMES.any? do |service|
+          !gateway_container_ids(service: service).empty?
+        end
     end
 
-    def gateway_container_ids(status: nil)
+    def gateway_container_ids(service:, status: nil)
       args = ["ps"]
       args << "--all" unless status
       args.concat(
@@ -163,7 +172,7 @@ module LocalDevelopmentGateway
           "--filter",
           "label=com.docker.compose.project=#{PROJECT_NAME}",
           "--filter",
-          "label=com.docker.compose.service=#{SERVICE_NAME}",
+          "label=com.docker.compose.service=#{service}",
           "--filter",
           "label=#{GATEWAY_LABEL}=true"
         ]
@@ -173,6 +182,12 @@ module LocalDevelopmentGateway
       output.lines.map(&:strip).reject(&:empty?)
     end
 
+    def obsolete_services_absent?
+      OBSOLETE_SERVICE_NAMES.all? do |service|
+        gateway_container_ids(service: service).empty?
+      end
+    end
+
     def healthy_container?(id)
       @runner.call(
         "inspect",
@@ -207,7 +222,8 @@ module LocalDevelopmentGateway
 
     def gateway_container?(container)
       container[:project] == PROJECT_NAME &&
-        container[:service] == SERVICE_NAME && container[:label] == "true"
+        SERVICE_NAMES.include?(container[:service]) &&
+        container[:label] == "true"
     end
   end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: local-development-gateway
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.2.1
 platform: ruby
 authors:
 - Marlen Brunner
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-12 00:00:00.000000000 Z
+date: 2026-10-08 00:00:00.000000000 Z
 dependencies: []
 description: Ruby API and CLI for starting, monitoring, and conditionally stopping
   the shared Docker gateway.
@@ -24,6 +24,18 @@ files:
 - config/traefik.yml
 - docker-compose.yml
 - lib/local_development_gateway.rb
+- lib/local_development_gateway/database_router.rb
+- lib/local_development_gateway/database_router/docker_api.rb
+- lib/local_development_gateway/database_router/docker_routes.rb
+- lib/local_development_gateway/database_router/drivers/postgre_sql_certificate.rb
+- lib/local_development_gateway/database_router/drivers/postgre_sql_driver.rb
+- lib/local_development_gateway/database_router/drivers/sql_server_driver.rb
+- lib/local_development_gateway/database_router/postgre_sql/cancellation_routes.rb
+- lib/local_development_gateway/database_router/postgre_sql/session.rb
+- lib/local_development_gateway/database_router/tds/message.rb
+- lib/local_development_gateway/database_router/tds/tls_byte_reader.rb
+- lib/local_development_gateway/database_router/tds/tls_client_hello.rb
+- lib/local_development_gateway/database_router/wire.rb
 - lib/local_development_gateway/version.rb
 homepage: https://github.com/icefoganalytics/local-development-gateway
 licenses: