local-development-gateway 0.1.3 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 10a939f848cae2b9e243772bb0b71e55f9f4ef7db51df904dbc44dceda981b0f
-  data.tar.gz: 0fe2303e0a7452356971343a371a73d897550d2461502bafba85ba81beb8bcba
+  metadata.gz: ad3ccae73de13d5b8f94f5745116e2c87cb323421b0df17efa76376648c5c99f
+  data.tar.gz: 628768727722325fcb3195d849de79e4c28e62f903618aaa50caf5b40e128500
 SHA512:
-  metadata.gz: 9a5b33aceca3f70ae6d50fe53dd6a398badbde7b2f7869a2099507bd361308843cc8189924cae4adb0c8203afe189c62a002ed694d73cb0efe9bc8089edab92e
-  data.tar.gz: '086a30b8f018bf0fd4ce44d410ba5dc23cbb4923d28afd225df171a1c9453a2a3f4cf2a24f8c2a4ed75fb3587f00aa9022cf03c4556a1e73ffc98f269936e95b'
+  metadata.gz: 29d3dc511c560f8df87b3cb960098084ba177d8b366bfb4cbea142dcaa59433431f9c9add4d823512440729150aec7442c4f1b9372e5ba5a77af1303b46598ac
+  data.tar.gz: 2e808de3a602575bc91b2585372f240de10ee46f90ec562d3e49619cd8153e5eac463b55697a9cad43558e149426d95ab870a8816e083f321e97944cdcb2d7e6

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,56 @@ 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.
+
+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. The PostgreSQL
+driver terminates client TLS at the gateway and forwards the resulting
+PostgreSQL stream over the private Docker network because PostgreSQL sends its
+TLS hostname only after the gateway accepts its SSL request. See
+[`docs/architecture/local-tcp-routing.md`](docs/architecture/local-tcp-routing.md)
+for the complete contract and security boundary.
+
 ## Development checks
 
 Install the locked development tools with `bundle install`. Run the Ruby
@@ -116,10 +166,17 @@ 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/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/tds/*.rb
 rake test
 ```
 

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,69 @@
+# 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 { |container| route(container) }
+      identities = routes.map { |route| [route.driver, route.hostname] }
+      unless identities.uniq.length == identities.length
+        raise Error, "Duplicate labelled database hostname"
+      end
+
+      routes.sort_by { |route| [route.driver, route.hostname] }
+    end
+
+    private
+
+    def route(container)
+      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
+
+      target_address =
+        container.dig("NetworkSettings", "Networks", NETWORK_NAME, "IPAddress")
+      return if target_address.nil? || target_address.empty?
+
+      DatabaseRouter::Route.new(
+        driver: driver,
+        hostname: hostname,
+        port: port,
+        target_address: target_address
+      )
+    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,60 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "local_development_gateway/database_router/wire"
+require "local_development_gateway/database_router/drivers/postgre_sql_certificate"
+
+module LocalDevelopmentGateway
+  module DatabaseRouter::Drivers
+    class PostgreSqlDriver
+      NAME = "postgresql"
+      LISTEN_PORT = 5432
+      SSL_REQUEST = [8, 80_877_103].pack("NN").freeze
+
+      def initialize(certificate: PostgreSqlCertificate.new)
+        @certificate = certificate
+      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,
+            SSL_REQUEST.bytesize,
+            deadline: deadline
+          )
+        raise Error, "PostgreSQL SSL is required" unless request == SSL_REQUEST
+        if routes.empty?
+          raise Error, "No labelled postgresql routes are available"
+        end
+
+        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 = false
+        DatabaseRouter::Wire.accept_tls(tls, deadline: deadline)
+        unless hostname
+          raise Error, "PostgreSQL TLS ClientHello does not contain SNI"
+        end
+
+        selected = routes.find { |route| route.hostname == hostname }
+        raise Error, "No PostgreSQL route for #{hostname}" unless selected
+
+        [tls, connector.call(selected)]
+      end
+    end
+  end
+end

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

@@ -0,0 +1,80 @@
+# 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
+      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)
+        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)
+          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
+        [client, target]
+      rescue StandardError
+        target&.close
+        raise
+      end
+
+      private
+
+      def negotiate(routes, prelogin, connector, deadline)
+        routes.each do |route|
+          target = connector.call(route)
+          DatabaseRouter::Tds::Message.write(target, prelogin)
+          return [
+            route,
+            target,
+            DatabaseRouter::Tds::Message.read(target, deadline: 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/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,61 @@
+# frozen_string_literal: true
+
+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
+        wait(io, readable: true, deadline: deadline)
+        bytes << io.readpartial(length - bytes.bytesize)
+      end
+      bytes
+    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,105 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "socket"
+
+module LocalDevelopmentGateway
+  class DatabaseRouter
+    CONNECT_TIMEOUT = 3
+    MAX_CONNECTIONS = 128
+    Route = Data.define(:driver, :hostname, :port, :target_address)
+
+    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
+    )
+      @routes = routes
+      @drivers = drivers
+      @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_CONNECTIONS)
+      MAX_CONNECTIONS.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)
+              ensure
+                slots << true
+              end
+            end
+          end
+        end
+        .each(&:join)
+    end
+
+    def route(client, driver)
+      routes = @routes.call.select { |route| route.driver == driver.name }
+
+      source, target =
+        driver.connect(client, routes, connector: method(:connect))
+      proxy(source, target)
+    rescue EOFError
+      nil
+    rescue Error => error
+      warn error.message
+    rescue StandardError => error
+      warn error.full_message
+    ensure
+      source&.close unless source.equal?(client)
+      client&.close
+      target&.close
+    end
+
+    private
+
+    def connect(route)
+      Socket.tcp(
+        route.target_address,
+        route.port,
+        connect_timeout: CONNECT_TIMEOUT
+      )
+    end
+
+    def proxy(client, target)
+      [[client, target], [target, client]].map do |source, destination|
+          Thread.new do
+            IO.copy_stream(source, destination)
+          rescue IOError, OpenSSL::SSL::SSLError, SystemCallError
+            nil
+          ensure
+            if destination.respond_to?(:close_write) && !destination.closed?
+              destination.close_write
+            end
+          end
+        end
+        .each(&:join)
+    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.0"
 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.0
 platform: ruby
 authors:
 - Marlen Brunner
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-12 00:00:00.000000000 Z
+date: 2026-08-14 00:00:00.000000000 Z
 dependencies: []
 description: Ruby API and CLI for starting, monitoring, and conditionally stopping
   the shared Docker gateway.
@@ -24,6 +24,16 @@ 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/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: