local-development-gateway 0.2.0 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ad3ccae73de13d5b8f94f5745116e2c87cb323421b0df17efa76376648c5c99f
-  data.tar.gz: 628768727722325fcb3195d849de79e4c28e62f903618aaa50caf5b40e128500
+  metadata.gz: 31c635514c35283b8ebab124d6a9f9ac8e17e8de5faaeb8573b0c73153b3efd4
+  data.tar.gz: 946d3a12335cff8a00f10a5ac330de37b5f5ec509a33779e44cefc265b8c0554
 SHA512:
-  metadata.gz: 29d3dc511c560f8df87b3cb960098084ba177d8b366bfb4cbea142dcaa59433431f9c9add4d823512440729150aec7442c4f1b9372e5ba5a77af1303b46598ac
-  data.tar.gz: 2e808de3a602575bc91b2585372f240de10ee46f90ec562d3e49619cd8153e5eac463b55697a9cad43558e149426d95ab870a8816e083f321e97944cdcb2d7e6
+  metadata.gz: 04b07e9aeb612b723744759bebb4f8e19319ac885a9dff3163446eaebcaf9a424cb203c36c89649a2378d1db675c5a167aade5bc0f33e6c82ccb70c11d7bcec6
+  data.tar.gz: 28528704687762d7a053b62f7c1fc1e7f5af76700e4c332efadaef32cb5c594e420af8bbd53803a1e3d0cecdafa3d892ceeee5edbac100aa388ea72e98a80de1

data/README.md

@@ -112,19 +112,102 @@ 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:
+### Three connection paths
+
+| Caller | Database hostname | Routing |
+| --- | --- | --- |
+| Application/API, background job, test container | `${COMPOSE_PROJECT_NAME}-<database-service>` | Qualified alias on that checkout's private `default` network; internal database port |
+| Desktop client, such as DBeaver | `db.<worktree>.<project>.localhost` | Encrypted, hostname-labelled gateway endpoint on loopback |
+| Database-local console, backup, clone command | `localhost` | Explicitly select the intended database container first |
+
+Do not use bare `db` or `db_trav_com` for application connections in the current
+gateway topology. An API attached to both `default` and `local-gateway` can see
+other projects' database service aliases on the shared network. Docker DNS or
+network ordering cannot reliably choose its own database. Separate database
+volumes do not prevent connecting to the wrong server.
+
+The qualified alias belongs **only on the private `default` network**. Compose
+project names must be distinct for concurrent checkouts. `.localhost` desktop
+names resolve to loopback, not to an internal database container; they are not
+substitutes for private aliases. Database cloning is independent of this
+hostname correction: it selects source/destination containers explicitly and
+connects locally.
+
+### Canonical development and test Compose pattern
+
+Merge these entries into the project's existing development base and gateway
+overlay. Keep its database images, credentials, volumes, and application
+commands. The base must not publish database host ports. Use the driver's
+existing configuration keys: `AZURE_SQL_HOST` is a SQL Server application
+example; `PGHOST` is the PostgreSQL/libpq equivalent. An application with a
+different PostgreSQL configuration key must set that key instead.
+
+For example, a wrapper-derived `COMPOSE_PROJECT_NAME=issue-123-example` gives
+private hosts `issue-123-example-db` and `issue-123-example-db_trav_com`.
+`GATEWAY_HOSTNAME=issue-123.example.localhost` separately identifies desktop
+routes. This requires no new Ruby API, generic database environment variable,
+or consumer runtime.
 
 ```yaml
+# docker-compose.development.yml: also safe without the gateway overlay.
 services:
+  api:
+    environment:
+      AZURE_SQL_HOST: "${COMPOSE_PROJECT_NAME}-db"
+      PGHOST: "${COMPOSE_PROJECT_NAME}-db_trav_com"
+  jobs:
+    environment:
+      AZURE_SQL_HOST: "${COMPOSE_PROJECT_NAME}-db"
+      PGHOST: "${COMPOSE_PROJECT_NAME}-db_trav_com"
+  test_api:
+    environment:
+      AZURE_SQL_HOST: "${COMPOSE_PROJECT_NAME}-db"
+      PGHOST: "${COMPOSE_PROJECT_NAME}-db_trav_com"
   db:
+    networks:
+      default:
+        aliases:
+          - "${COMPOSE_PROJECT_NAME}-db"
+  db_trav_com:
+    networks:
+      default:
+        aliases:
+          - "${COMPOSE_PROJECT_NAME}-db_trav_com"
+```
+
+The example's driver assignments are illustrative. In
+[Travel Authorization's overlay](https://github.com/icefoganalytics/travel-authorization/blob/main/docker-compose.development.gateway.yml),
+`db` is PostgreSQL and `db_trav_com` is SQL Server: its PostgreSQL host setting
+must use `${COMPOSE_PROJECT_NAME}-db`, and its SQL Server host setting must use
+`${COMPOSE_PROJECT_NAME}-db_trav_com`, with labels/ports matching those drivers.
+Apply the rule separately to **every** database service, even when two services
+use the same driver. Preserve each context's existing credentials, internal
+port, and database name; tests must still select the test database rather than
+development data.
+
+```yaml
+# docker-compose.development.gateway.yml
+services:
+  api:
     networks:
       - default
       - local-gateway
+  db:
+    networks:
+      default: {}
+      local-gateway: {}
     labels:
       - "local-gateway.tcp.driver=sql_server"
-      - "local-gateway.tcp.hostname=db.${GATEWAY_HOSTNAME:-wrap.localhost}"
+      - "local-gateway.tcp.hostname=db.${GATEWAY_HOSTNAME}"
       - "local-gateway.tcp.port=1433"
+  db_trav_com:
+    networks:
+      default: {}
+      local-gateway: {}
+    labels:
+      - "local-gateway.tcp.driver=postgresql"
+      - "local-gateway.tcp.hostname=db.${GATEWAY_HOSTNAME}"
+      - "local-gateway.tcp.port=5432"
 
 networks:
   local-gateway:
@@ -132,16 +215,64 @@ networks:
     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:
+Use **mapping-form** database networks in both files. Compose merges
+`default: {}` with the base's `default.aliases`; replacing that mapping with a
+network list can lose the private alias. Do not add qualified aliases to
+`local-gateway`. Jobs/tests need only `default` unless they themselves expose a
+routed service; qualified database names remain safe if an existing overlay
+also attaches them to the shared network.
+
+The shared router owns `127.0.0.1:1433` and `127.0.0.1:5432`. No participating
+database publishes either port, so multiple development/test stacks can start
+concurrently. Internal connections use each server's internal port and existing
+encryption policy; they do not pass through the router or require a published
+port.
+
+### Explicit non-gateway fallback
+
+Container-only development/tests work with the base alone. If desktop access
+without the gateway is required, select a separate, project-local publishing
+overlay **instead of** the gateway overlay:
+
+```yaml
+# docker-compose.development.ports.yml: opt-in, non-gateway mode only.
+services:
+  db:
+    ports:
+      - "127.0.0.1:1433:1433"
+  db_trav_com:
+    ports:
+      - "127.0.0.1:5432:5432"
+```
+
+These fallback ports must be free; this mode does not promise parallel desktop
+access. Do not combine it with the gateway or leave these publications in the
+base/test files. When migrating a project that retains base publications, its
+gateway overlay must explicitly clear each database's ports with
+`ports: !reset []` (Docker Compose 2.24.4 or newer); simply omitting `ports` or
+setting `ports: []` does not remove inherited publications. Prefer the
+port-free base plus explicit fallback above.
+
+Use the project's documented development wrapper to select Compose modes and
+start/test/stop services. Inspect its rendered `config`: gateway mode must have
+no database host publications and must retain the private aliases. A base-only
+test wrapper must use the same qualified hosts.
+
+### Desktop database clients
+
+For `GATEWAY_HOSTNAME=issue-123.example.localhost`, connect to
+`db.issue-123.example.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` |
+| `postgresql` | `5432` | SSL mode `require`, SNI enabled, development certificate accepted |
 
 Use the database container's actual internal port in
-`local-gateway.tcp.port`; it does not need to match the host listener.
+`local-gateway.tcp.port`; it need not match the host listener. Different drivers
+can share a hostname because their listeners differ. Two databases using the
+same driver need distinct labels, for example `db.${GATEWAY_HOSTNAME}` and
+`db_trav_com.${GATEWAY_HOSTNAME}`.
 
 All `.localhost` names resolve to loopback. The gateway publishes loopback-only
 listeners, discovers labelled containers through Docker, and uses the database
@@ -149,12 +280,38 @@ 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.
+
+### Downstream adoption checklist
+
+1. Give each concurrent checkout a distinct Compose project name and desktop
+   route hostname. Qualify every API/job/test database host with
+   `${COMPOSE_PROJECT_NAME}-<database-service>` using its existing driver setting.
+2. Advertise each qualified alias only on its private `default` network;
+   preserve it through mapping-form network merges in base-only and gateway modes.
+3. Remove fixed database publications from development/test stacks; retain
+   desktop fallback publications only in an explicitly selected non-gateway file.
+4. Recreate database and consumer services so changed aliases and environment
+   settings take effect. Inspect both rendered Compose configurations.
+5. Query real, read-only server/database identity from API, job, and test
+   contexts and compare it with the explicitly selected local database
+   container. Stop that checkout's database while another is available: its
+   consumers must fail, not select the other checkout. Record the actual DNS or
+   connection error; there is no universal platform error code.
+6. Verify both encrypted desktop routes, and restore normal gateway attachments
+   after test wrappers recreate services using base-only Compose.
+
+Shared development networks are not a hostile-container security boundary.
+Qualified private aliases prevent accidental cross-stack selection; they do not
+prevent an attached, malicious container from connecting to another database.
 
 ## Development checks
 
@@ -169,6 +326,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 +334,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
 ```
@@ -195,8 +354,8 @@ The gateway owns the single browser port on `127.0.0.1:80`. Participating projec
 
 The gateway:
 
-- listens only on `127.0.0.1:80`;
-- creates the external Docker network `local-gateway`;
+- listens only on `127.0.0.1:80`, `127.0.0.1:1433`, and `127.0.0.1:5432`;
+- creates the external Docker network `local-gateway` for HTTP and labelled database ingress;
 - discovers only services explicitly labelled for routing;
 - has the Docker label `local-gateway=true` so a project can detect it.
 
@@ -225,6 +384,14 @@ Use a project- and service-prefixed router/service identifier. Never derive a de
 
 Without the gateway, a participating project may use its own loopback port-publishing fallback. That fallback is project-specific and is not part of the shared gateway contract.
 
+Application/job/test database connections follow the
+[private-alias contract](#three-connection-paths), not desktop gateway hostnames
+or bare database service names. Database services retain their private network
+and add gateway labels without publishing host ports. The
+[architecture decision](docs/architecture/local-tcp-routing.md#internal-database-isolation-decision)
+explains why a future HTTP/database ingress split requires coordinated consumer
+migration rather than a transparent gem update.
+
 ## Authentication callbacks
 
 A wildcard hostname lets an identity provider allow one local callback pattern instead of every generated port. For Traditional Knowledge, configure:
@@ -251,3 +418,29 @@ 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.2
+
+- Canonical SQL Server/PostgreSQL Compose integration supports concurrent
+  development/test stacks without per-stack database host publications.
+- Application, job, and test connections use checkout-qualified private aliases
+  instead of ambiguous shared-network service names. Base-only mode, explicit
+  non-gateway fallback, multiple databases, and adoption checks are documented.
+- The packaged architecture reference records the current private-alias
+  decision, real-container Linux validation, and coordinated migration required
+  for a future HTTP/database ingress split.
+- Gateway routing and the public Ruby API are unchanged. Consumers must adopt
+  the Compose contract; upgrading the gem does not rewrite their configuration.
+
+## 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/docs/architecture/local-tcp-routing.md

@@ -0,0 +1,356 @@
+# Local TCP Routing Architecture
+
+Status: SQL Server and PostgreSQL protocol routing implemented in PR #22 and
+validated on Linux. Windows Docker Desktop validation remains outstanding.
+
+## Request
+
+Extend Local Development Gateway so a participating Docker Compose project can
+expose hostname-routed database services with the same simple declarative
+integration it already uses for HTTP services.
+
+For WRAP, database routing should require only a small change to
+`docker-compose.development.gateway.yml`. WRAP must not implement address
+allocation, routing, DNS, host-file management, startup orchestration, or
+cleanup.
+
+The initial endpoints are:
+
+```text
+db.<worktree>.wrap.localhost:1433 # SQL Server
+db.<worktree>.wrap.localhost:5432 # PostgreSQL
+```
+
+Each must connect from DBeaver to that worktree's labelled database container.
+
+## Consumer Contract
+
+A participating project keeps its databases on its private `default` network
+and adds the existing `local-gateway` network plus three gateway-owned labels:
+driver, desktop hostname, and internal port. The copyable SQL Server and
+PostgreSQL base/overlay examples live in the README's
+[canonical Compose pattern](../../README.md#canonical-development-and-test-compose-pattern).
+
+| Connection path | Destination selection |
+| --- | --- |
+| API, background job, test | `${COMPOSE_PROJECT_NAME}-<database-service>` on private Docker DNS, using the driver's existing host setting and internal port |
+| Desktop database client | Encrypted `db.<worktree>.<project>.localhost` endpoint; driver/hostname labels select the backend |
+| Database-local console, backup, clone | Explicitly selected container, then `localhost`; not gateway routing |
+
+Each concurrent checkout has a distinct Compose project name. Each database
+advertises its qualified alias only on that project's `default` network.
+Use mapping-form database networks in the base and gateway overlay so Compose
+preserves `default.aliases`. Configure all application/job/test contexts with
+their appropriate aliases, existing credentials, and intended database names;
+test contexts still select their own test database.
+
+Gateway-mode development and test stacks publish no database host ports.
+Container consumers work with the base alone. Desktop access without the
+gateway is an explicit project-local port-publishing overlay, not an inherited
+base default and not a parallel-stack guarantee. The README covers migration
+of inherited port publications, fallback selection, and adoption checks.
+
+Internal database hostnames and desktop `.localhost` hostnames are separate
+contracts. Internal connections need neither a published host port nor the
+gateway's encrypted-handshake protocol. Database cloning does not depend on
+the internal hostname correction.
+
+Requirements:
+
+- No consumer Ruby API calls.
+- No consumer-side address allocator.
+- No per-worktree host-port selection.
+- No bind-address environment variable passed from application code.
+- No consumer startup or shutdown hook solely for gateway routing.
+- No consumer cleanup call.
+- No manually maintained DBeaver port per worktree.
+- The consumer supplies only declarative service identity and internal-port metadata.
+
+- No administrator or root installation.
+- No host `/etc/hosts`, DNS, resolver, systemd, or Windows-service changes.
+- The same gateway Compose stack must run through Docker on Linux and Windows.
+
+## Internal Database Isolation Decision
+
+**Decision:** retain the current shared ingress topology and standardize
+checkout-qualified private aliases. This resolves
+[#23](https://github.com/icefoganalytics/local-development-gateway/issues/23)'s
+parallel-stack contract and
+[#26](https://github.com/icefoganalytics/local-development-gateway/issues/26)'s
+internal database selection contract without new runtime machinery or public
+Ruby lifecycle changes.
+
+Bare `db` is not safe for an API attached to both its private bridge and
+`local-gateway`: other attached databases advertise the same Compose service
+alias on shared ingress. Docker DNS/network ordering, container IDs, separate
+volumes, and gateway TLS/SNI cannot disambiguate an ordinary internal connection.
+The qualified alias identifies only its own private endpoint. If that endpoint
+is absent, its consumers must fail rather than connect to another checkout.
+Do not advertise the qualified alias on shared ingress.
+
+An HTTP/database ingress split is a possible future centralization, not a
+transparent gem-only patch:
+
+- HTTP services/APIs: private checkout network plus existing HTTP ingress.
+- Databases: private checkout network plus a distinct gateway-owned database
+  ingress network. APIs/jobs/tests must not join database ingress.
+- Traefik: HTTP ingress only. Database router: database ingress only.
+- Route discovery must read backend addresses on database ingress instead of
+  `DockerRoutes::NETWORK_NAME`'s current `local-gateway`.
+- Gateway readiness/discovery must check the appropriate networks and services.
+  Unused-gateway shutdown must retain running consumers on either ingress,
+  including database-only stacks, without counting exited containers.
+- Consumer network membership, installed gem versions, and already-running
+  shared gateways require coordinated migration. Old consumers still
+  advertising database aliases on HTTP ingress remain ambiguous after a
+  gateway-only update.
+
+That alternative requires packaged install/readiness, database-only lifecycle,
+multi-project startup/stop/replacement, SQL Server routing, PostgreSQL routing
+and cancellation, mixed-version migration, and unchanged HTTP-routing evidence
+before adoption. No structural split is implemented in this release; downstream
+qualified-alias mitigations must remain until a verified replacement is adopted.
+
+These development networks are not hostile-container security boundaries.
+Private qualified aliases prevent accidental selection, not deliberate
+connections by another attached container.
+
+## Gateway Responsibilities
+
+All implementation belongs in this repository. The gateway must:
+
+1. Discover participating containers and their routing metadata through Docker.
+2. Derive or read the requested hostname and target internal port.
+3. Distinguish concurrent worktrees even when they expose the same internal TCP port.
+4. Make `db.<worktree>.wrap.localhost` resolve or connect to the correct worktree route on the local machine.
+5. Forward the raw TCP stream to the labelled container.
+6. Add, update, and remove routes automatically as containers start, restart, and stop.
+7. Preserve stable routing for a worktree while it remains active.
+8. Keep all listeners and generated routes local to the developer machine.
+9. Preserve the existing HTTP routing behavior.
+
+## Implemented Routing Shape
+
+Every `.localhost` name intentionally resolves to loopback on both Linux and
+Windows. A shared port therefore requires a protocol-level hostname. The
+gateway uses one Docker-label discovery path and a small driver for each
+supported database handshake:
+
+```text
+DBeaver
+  -> db.<worktree>.wrap.localhost:<driver port>
+  -> Docker publishes the database router on loopback
+  -> driver reads the encrypted handshake hostname
+  -> router selects the matching Docker label
+  -> router forwards the database stream to the labelled container
+```
+
+The `sql_server` driver mediates Tabular Data Stream (TDS) PRELOGIN, reads SNI
+from the wrapped TLS ClientHello, then preserves the encrypted client/backend
+stream. The
+`postgresql` driver accepts PostgreSQL's SSLRequest, terminates the client TLS
+session to obtain SNI, and forwards the plaintext PostgreSQL stream on the
+private Docker network.
+
+Traefik remains responsible for HTTP. It cannot inspect TLS SNI wrapped inside
+TDS PRELOGIN. It **does** support PostgreSQL SSLRequest/STARTTLS and subsequent
+TLS-SNI routing, as documented in its
+[TCP TLS reference](https://doc.traefik.io/traefik/reference/routing-configuration/tcp/tls/).
+
+STARTTLS alone is therefore not a reason to implement PostgreSQL routing here.
+The gateway also owns PostgreSQL query cancellation: `psql` and JDBC can open
+a separate plaintext CancelRequest connection containing only a backend PID and
+secret, with no hostname. A stateless SNI router cannot select that backend.
+Keeping negotiation and cancellation-aware session forwarding together preserves
+the existing three-label consumer contract without per-route internal listeners,
+generated Traefik configuration, or another discovery/control plane.
+
+Normal database sessions require encrypted handshakes so the requested hostname
+is present as TLS SNI. PostgreSQL cancellation is a bounded control-message
+exception, not support for plaintext database sessions. The router parses
+PostgreSQL backend messages only until BackendKeyData, replaces that key, then
+forwards the remainder without interpreting query results.
+
+## Code Organization
+
+`DatabaseRouter` owns listener concurrency and backend connection lifecycle.
+`Wire` owns bounded handshake I/O and bidirectional forwarding, including
+shutdown that wakes both relay directions. `DockerApi` and `DockerRoutes` form
+the external Docker boundary and produce validated `Route` values.
+Behavior-bearing classes each have one file, and directories map to Ruby
+namespaces: drivers live under `DatabaseRouter::Drivers`, TDS framing and TLS
+parsing under `DatabaseRouter::Tds`, and PostgreSQL session-key forwarding and
+cancellation lookup under `DatabaseRouter::PostgreSql`. Tiny immutable `Route`,
+`Connection`, cancellation destination, and TDS `Packet` records stay with
+their owners.
+
+Source and test imports resolve from the gem's `lib` load path and start at
+`local_development_gateway`; domain files never traverse sibling paths with
+`require_relative`.
+
+The focused tests mirror those boundaries under `test/database_router/`.
+Protocol scenarios keep their literal setup beside the behavior they verify
+instead of sharing a generic fixture layer.
+
+## Hostname Contract
+
+- Keep the established WRAP hostname family.
+- HTTP remains:
+  - `<worktree>.wrap.localhost`
+  - `api.<worktree>.wrap.localhost`
+  - `mail.<worktree>.wrap.localhost`
+- SQL Server is:
+  - `db.<worktree>.wrap.localhost`
+- PostgreSQL uses the same hostname on port `5432`.
+- Do not migrate consumers to `.test`, `.alt`, `.local`, `home.arpa`, or an externally registered domain as part of this issue.
+- Do not require host resolver configuration; `.localhost` must retain its native loopback behavior.
+
+## Security Boundary
+
+- No routed service may be reachable from another machine.
+- Bind host listeners only to loopback addresses.
+- Do not publish generated names through public DNS.
+- Do not expose SQL Server on `0.0.0.0` or a LAN interface.
+- Do not require privileged host integration.
+- Do not grant a long-running container unrestricted write access to arbitrary host files.
+- The database router receives the same read-only Docker socket already required by Traefik so it can resolve labels to current container addresses.
+- SQL Server remains encrypted end to end. PostgreSQL is plaintext only inside the private Docker network after the gateway terminates client TLS.
+
+## Lifecycle
+
+- Normal session selection reads current Docker metadata; starting, restarting,
+  or stopping a labelled container requires no stored route configuration or
+  consumer cleanup.
+- Containers outside `local-gateway` are excluded before label validation.
+  Invalid participating routes are warned about and quarantined individually.
+- Duplicate active driver/hostname identities reject every route for that
+  identity, not unrelated identities or database drivers.
+- A connection snapshot never changes backend after selection.
+- PostgreSQL rewrites BackendKeyData with a random, collision-checked virtual
+  identity whose PID is positive for older client compatibility. The active
+  mapping retains the exact backend address, port, and original cancellation key.
+- Cancellation uses that mapping without Docker discovery or hostname
+  negotiation. Unknown and closed-session identities fail closed, and malformed
+  cancellation lengths never fall through to normal backend forwarding.
+- Backend EOF, client disconnect, or relay failure removes the session mapping.
+  Gateway restart closes sessions and clears their cancellation identities;
+  normal route configuration is reconstructed from Docker metadata.
+- Handshakes and active sessions have separate bounded admission pools.
+  Cancellation and closed health probes do not consume an active-session slot,
+  so cancellation remains available when the normal session limit is reached.
+- SQL Server provisional attempts have a bounded sub-deadline within the shared
+  handshake deadline. Connection establishment uses only the remaining budget;
+  stalled provisional sockets are closed before a healthy alternative is tried.
+
+## Compatibility
+
+- DBeaver connects to `db.<worktree>.wrap.localhost` on `1433` for SQL Server
+  or `5432` for PostgreSQL.
+- SQL Server clients must enable encryption and trust the development server
+  certificate.
+- PostgreSQL clients must use SSL mode `require`, send SNI, and permit the
+  gateway's generated development certificate.
+- Concurrent SQL Server routes must use compatible PRELOGIN encryption
+  settings because the client receives a provisional backend's negotiation
+  response before SNI identifies the final backend.
+- PostgreSQL backends must accept a plaintext connection from the private
+  `local-gateway` Docker network.
+- PostgreSQL cancellation PIDs reported by client APIs are virtual. Use
+  `SELECT pg_backend_pid()` when inspecting the physical backend in server views.
+- Existing browser routes through Traefik on `127.0.0.1:80` remain unchanged.
+- Multiple active worktrees can use each database driver's standard port
+  simultaneously.
+- Adding another protocol requires another explicit driver; ports are never
+  inferred from labels.
+
+## Acceptance Scenarios
+
+1. Start worktree A and worktree B with the same database driver and internal
+   port.
+2. Connect a DBeaver-equivalent client to
+   `db.<A>.wrap.localhost:<driver port>`; observe bytes reaching only A.
+3. Connect to `db.<B>.wrap.localhost:<driver port>`; observe bytes reaching
+   only B.
+4. Repeat the routing check for both `sql_server` and `postgresql`.
+5. Keep both connections possible concurrently without alternate host ports.
+6. Recreate A's database container; the same hostname routes to its replacement.
+7. Stop A; A's route disappears while B remains available.
+8. Verify existing HTTP hostnames still use Traefik.
+9. Verify every host listener is loopback-only.
+10. Demonstrate consumer integration as a Compose-only diff.
+
+## Non-Goals
+
+- Changing consumer application code, adding new development wrapper runtimes,
+  or automatically mutating consumer networks. Existing Compose connection
+  settings and file selection must adopt the documented contract.
+- Requiring consumers to run DNS, a proxy, or host installation.
+- Assigning a different database port to each worktree.
+- Publishing development routes outside the machine.
+- Replacing existing HTTP routing.
+- Building a generic service mesh or full database proxy.
+- Supporting plaintext database sessions, PostgreSQL direct TLS negotiation, or
+  database protocols without an implemented driver. Plaintext PostgreSQL
+  cancellation control packets are supported.
+
+## Verification Evidence
+
+PR #22 demonstrated:
+
+1. Two exact `db.<worktree>.wrap.localhost` names selected different labelled
+   containers for SQL Server and PostgreSQL.
+2. Docker-label discovery updated routes without consumer lifecycle code;
+   stopped routes were rejected while surviving routes remained reachable.
+3. Fragmented and oversized handshakes, stalled clients, duplicate routes,
+   unsupported drivers, and unreachable provisional backends failed safely.
+4. Linux validation required no host resolver, administrator/root, or
+   operating-system service setup. Windows Docker Desktop was unavailable for
+   equivalent validation.
+5. Existing HTTP routes remained unchanged and every published listener was
+   loopback-only.
+
+Issue #24's corrective release additionally demonstrated:
+
+1. PostgreSQL 14.4 `psql` cancellation stopped A's query while B stayed active.
+2. DBeaver's Java runtime with PostgreSQL JDBC 42.7.13 and 42.2.27 returned
+   SQLSTATE `57014` for A while B completed its query normally.
+3. Two SQL Server 2022 backends remained reachable with encrypted `sqlcmd`
+   connections despite a first labelled backend that accepted TCP but never
+   answered PRELOGIN.
+4. Focused regressions cover invalid-route isolation, cancellation identity
+   collisions after PID normalization, variable backend keys, session cleanup,
+   malformed cancellation packets, and cancellation at full session capacity.
+
+Issues #23 and #26's documentation release demonstrated on Linux with Docker
+Compose 5.6.0:
+
+1. Two isolated Compose projects, each with SQL Server 2022 `db` and PostgreSQL
+   17 `db_trav_com`, started concurrently without database host publications.
+   The repository's `bin/dev` Compose passthrough selected the temporary
+   consumer fixtures; the existing shared gateway was reused.
+2. Real SQL/PG client containers representing API, job, and test contexts joined
+   both private and shared networks. `getent hosts` selected only their private
+   qualified aliases. Read-only SQL Server `@@SERVERNAME` / `DB_NAME()` and
+   PostgreSQL `cluster_name` / `current_database()` / `inet_server_addr()`
+   identified their own servers. Test contexts selected `qa_test`; explicit
+   database-container `localhost` queries matched the consumer identities.
+3. Stopping A's two databases made every A context fail while B remained
+   usable. `getent hosts` returned exit 1; SQL Server reported login timeout,
+   TCP Provider `0x2AFA`, and server-not-found/not-accessible; PostgreSQL reported
+   `could not translate host name ... to address: Try again`. These are observed
+   platform errors, not required portable error codes.
+4. Both projects were recreated using base-only Compose. All consumer identity
+   checks passed with private-only attachments. Recreating with the gateway
+   overlay restored shared attachments and preserved private aliases and test
+   database selection.
+5. Desktop-equivalent host-network clients selected both labelled worktrees:
+   `sqlcmd` 18.6 with `-Nm -C` (mandatory encryption, trusted development
+   certificate), and PostgreSQL 17 `psql` with `sslmode=require`, SNI, hostname,
+   and explicit loopback `hostaddr`. SQL Server strict/direct TLS is outside the
+   supported TDS PRELOGIN contract.
+6. Docker inspection confirmed the shared gateway publishes only
+   `127.0.0.1:80`, `127.0.0.1:1433`, and `127.0.0.1:5432`.
+
+This validates real database client contexts, not an automatic downstream
+application migration. Consumers still need to adopt the README checklist.
+Windows Docker Desktop validation remains outstanding.

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.2"
 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.2
 platform: ruby
 authors:
 - Marlen Brunner
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-14 00:00:00.000000000 Z
+date: 2026-10-14 00:00:00.000000000 Z
 dependencies: []
 description: Ruby API and CLI for starting, monitoring, and conditionally stopping
   the shared Docker gateway.
@@ -23,6 +23,7 @@ files:
 - bin/local-development-gateway
 - config/traefik.yml
 - docker-compose.yml
+- docs/architecture/local-tcp-routing.md
 - lib/local_development_gateway.rb
 - lib/local_development_gateway/database_router.rb
 - lib/local_development_gateway/database_router/docker_api.rb
@@ -30,6 +31,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