local-development-gateway 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ad3ccae73de13d5b8f94f5745116e2c87cb323421b0df17efa76376648c5c99f
-  data.tar.gz: 628768727722325fcb3195d849de79e4c28e62f903618aaa50caf5b40e128500
+  metadata.gz: 8baffa29acc52adfcc3112cacc9be936b24528915f86fbc94c323df081e05fd5
+  data.tar.gz: 4ab5156e3dc8dae143345b3c58271be2afd4b3485fb92c6bfd18153dd1958734
 SHA512:
-  metadata.gz: 29d3dc511c560f8df87b3cb960098084ba177d8b366bfb4cbea142dcaa59433431f9c9add4d823512440729150aec7442c4f1b9372e5ba5a77af1303b46598ac
-  data.tar.gz: 2e808de3a602575bc91b2585372f240de10ee46f90ec562d3e49619cd8153e5eac463b55697a9cad43558e149426d95ab870a8816e083f321e97944cdcb2d7e6
+  metadata.gz: 8ed0938cfb210bda2c320f6c481af5ddabf9f32d8f04fcac7ac94f60bbc9df8da98fe71f7929581d54ab5a20b648c339b92cd78f799b50fb74f3300e64997e0c
+  data.tar.gz: b1acdaefc1c2b69b1e101fb5516ee8de7de866e9d9b1d11bd2390d14a860204a869ca8d90a10123a9b304b954fb03297c26b80482743105bee5a53f3bad06c22

data/README.md

@@ -143,18 +143,27 @@ connects to `db.issue-567.wrap.localhost` on the driver's standard port:
 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. 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
+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.
+for the complete contract and security boundary, including the reason for
+retaining cancellation-aware PostgreSQL routing despite Traefik's STARTTLS support.
 
 ## Development checks
 
@@ -169,6 +178,7 @@ bundle exec ruby "$(bundle show syntax_tree)/exe/stree" check \
   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 \
@@ -176,6 +186,7 @@ bundle exec ruby "$(bundle show syntax_tree)/exe/stree" check \
   test/*.rb \
   test/database_router/*.rb \
   test/database_router/drivers/*.rb \
+  test/database_router/postgre_sql/*.rb \
   test/database_router/tds/*.rb
 rake test
 ```
@@ -251,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/lib/local_development_gateway/database_router/docker_routes.rb

@@ -18,18 +18,35 @@ module LocalDevelopmentGateway
       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"
+          .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.sort_by { |route| [route.driver, route.hostname] }
+      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]
@@ -52,16 +69,14 @@ module LocalDevelopmentGateway
         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 KeyError
+      raise Error, "Incomplete labelled database route"
     rescue ArgumentError, TypeError
       raise Error, "Invalid labelled database port: #{port}"
     end

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

@@ -1,8 +1,10 @@
 # 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
@@ -10,9 +12,14 @@ module LocalDevelopmentGateway
       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)
+      def initialize(
+        certificate: PostgreSqlCertificate.new,
+        cancellations: DatabaseRouter::PostgreSql::CancellationRoutes.new
+      )
         @certificate = certificate
+        @cancellations = cancellations
       end
 
       def name
@@ -23,18 +30,15 @@ module LocalDevelopmentGateway
         LISTEN_PORT
       end
 
-      def connect(client, routes, connector:)
+      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"
+          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
@@ -44,16 +48,78 @@ module LocalDevelopmentGateway
             nil
           end
         tls = OpenSSL::SSL::SSLSocket.new(client, context)
-        tls.sync_close = false
+        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.find { |route| route.hostname == hostname }
+        selected = routes.call.find { |route| route.hostname == hostname }
         raise Error, "No PostgreSQL route for #{hostname}" unless selected
 
-        [tls, connector.call(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

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

@@ -6,6 +6,8 @@ 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
 
@@ -17,9 +19,10 @@ module LocalDevelopmentGateway
         LISTEN_PORT
       end
 
-      def connect(client, routes, connector:)
+      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
@@ -33,7 +36,7 @@ module LocalDevelopmentGateway
 
         if selected != provisional
           target.close
-          target = connector.call(selected)
+          target = connector.call(selected, deadline: deadline)
           DatabaseRouter::Tds::Message.write(target, prelogin)
           DatabaseRouter::Tds::Message.read(target, deadline: deadline)
         end
@@ -41,22 +44,41 @@ module LocalDevelopmentGateway
         messages.each do |message|
           DatabaseRouter::Tds::Message.write(target, message)
         end
-        [client, target]
+        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|
-          target = connector.call(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: deadline)
+            DatabaseRouter::Tds::Message.read(
+              target,
+              deadline: attempt_deadline
+            )
           ]
         rescue Error, EOFError, IOError, SystemCallError
           target&.close

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/wire.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require "openssl"
+require "socket"
+
 module LocalDevelopmentGateway
   module DatabaseRouter::Wire
     HANDSHAKE_TIMEOUT = 5
@@ -13,12 +16,70 @@ module LocalDevelopmentGateway
     def read_exactly(io, length, deadline:)
       bytes = +""
       while bytes.bytesize < length
-        wait(io, readable: true, deadline: deadline)
-        bytes << io.readpartial(length - bytes.bytesize)
+        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

data/lib/local_development_gateway/database_router.rb

@@ -7,7 +7,9 @@ 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
@@ -23,10 +25,13 @@ module LocalDevelopmentGateway
     def initialize(
       routes: DockerRoutes.new,
       drivers: self.class.drivers,
-      servers: nil
+      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|
@@ -35,8 +40,8 @@ module LocalDevelopmentGateway
     end
 
     def run
-      slots = SizedQueue.new(MAX_CONNECTIONS)
-      MAX_CONNECTIONS.times { slots << true }
+      slots = SizedQueue.new(MAX_HANDSHAKES)
+      MAX_HANDSHAKES.times { slots << true }
       @drivers
         .map do |driver|
           Thread.new do
@@ -45,9 +50,7 @@ module LocalDevelopmentGateway
               client = server.accept
               slots.pop
               Thread.new(client) do |connection|
-                route(connection, driver)
-              ensure
-                slots << true
+                route(connection, driver, handshake_slots: slots)
               end
             end
           end
@@ -55,48 +58,46 @@ module LocalDevelopmentGateway
         .each(&:join)
     end
 
-    def route(client, driver)
-      routes = @routes.call.select { |route| route.driver == driver.name }
+    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
 
-      source, target =
-        driver.connect(client, routes, connector: method(:connect))
-      proxy(source, target)
+      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
-      source&.close unless source.equal?(client)
+      handshake_slots&.push(true)
+      @session_slots << true if session_slot
+      connection&.source&.close
       client&.close
-      target&.close
+      connection&.target&.close
     end
 
     private
 
-    def connect(route)
+    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
+        connect_timeout: [CONNECT_TIMEOUT, remaining].min
       )
     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
 

data/lib/local_development_gateway/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: local-development-gateway
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Marlen Brunner
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-14 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.
@@ -30,6 +30,8 @@ files:
 - 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