local-development-gateway 0.2.1 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8baffa29acc52adfcc3112cacc9be936b24528915f86fbc94c323df081e05fd5
-  data.tar.gz: 4ab5156e3dc8dae143345b3c58271be2afd4b3485fb92c6bfd18153dd1958734
+  metadata.gz: 31c635514c35283b8ebab124d6a9f9ac8e17e8de5faaeb8573b0c73153b3efd4
+  data.tar.gz: 946d3a12335cff8a00f10a5ac330de37b5f5ec509a33779e44cefc265b8c0554
 SHA512:
-  metadata.gz: 8ed0938cfb210bda2c320f6c481af5ddabf9f32d8f04fcac7ac94f60bbc9df8da98fe71f7929581d54ab5a20b648c339b92cd78f799b50fb74f3300e64997e0c
-  data.tar.gz: b1acdaefc1c2b69b1e101fb5516ee8de7de866e9d9b1d11bd2390d14a860204a869ca8d90a10123a9b304b954fb03297c26b80482743105bee5a53f3bad06c22
+  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,22 +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.
-
-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.
+`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
@@ -165,6 +290,29 @@ Closed sessions lose their cancellation mapping. See
 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
 
 Install the locked development tools with `bundle install`. Run the Ruby
@@ -206,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.
 
@@ -236,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:
@@ -263,6 +419,19 @@ It mounts the Docker socket so it can discover labelled containers. A read-only
 | 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

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

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module LocalDevelopmentGateway
-  VERSION = "0.2.1"
+  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.1
+  version: 0.2.2
 platform: ruby
 authors:
 - Marlen Brunner
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-08 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