local-development-gateway 0.2.2 → 0.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 31c635514c35283b8ebab124d6a9f9ac8e17e8de5faaeb8573b0c73153b3efd4
-  data.tar.gz: 946d3a12335cff8a00f10a5ac330de37b5f5ec509a33779e44cefc265b8c0554
+  metadata.gz: 769fae659862a5e04bbb1f4c1d572552afe3f777f4bbbd4ec007fa02860639c6
+  data.tar.gz: e704decf7f614cb01a2a74ae1601fa6e925da9c243b3b4015ea9760e8ec45ae0
 SHA512:
-  metadata.gz: 04b07e9aeb612b723744759bebb4f8e19319ac885a9dff3163446eaebcaf9a424cb203c36c89649a2378d1db675c5a167aade5bc0f33e6c82ccb70c11d7bcec6
-  data.tar.gz: 28528704687762d7a053b62f7c1fc1e7f5af76700e4c332efadaef32cb5c594e420af8bbd53803a1e3d0cecdafa3d892ceeee5edbac100aa388ea72e98a80de1
+  metadata.gz: 247d626136bee33123253a419d036812041b6e5df6094b14b262f5bc6be7ac629083aea1b717b64f8b29afce69b245b739fff47c0bcebc53c80b496351dbbb50
+  data.tar.gz: 6954a6378a4aecf2d6c3d6eef08d8be001abfd2fc5c1758314b37b777d795ea6e7e7f16ec647eb128b0930353128f8c6f7be25539b1444d629f2dddd35e2ec7a

data/README.md

@@ -106,6 +106,21 @@ command that must not start a missing gateway, pass
 `ensure_running: false`; the block still runs and unused-gateway cleanup is
 attempted.
 
+### Installed versus active versions
+
+`bundle exec local-development-gateway status` reports the invoking gem's installed version separately from each running shared service's active version, provenance, and mounted asset path. Healthy CLI `up`/`ensure` reuse also prints these diagnostics without recreating containers. Ruby callers can inspect `LocalDevelopmentGateway.status`; `ensure_running` still returns `:reused` for healthy services, and `ready?` remains a health check, not an artifact-version check.
+
+For the database router, the active version comes from a record written by the Ruby process after loading the library at startup. For the HTTP gateway, it is the gateway configuration artifact version recorded in a container-creation label, not the Traefik image version. Missing records or labels are `unknown`. A legacy mount path containing a gem version is useful diagnostic evidence but does not prove which Ruby code or configuration the running process loaded. Neither version record is a content hash or proof that bind-mounted files have remained unchanged.
+
+Installing a newer gem does not update already-running services. A known difference is reported as `mismatch`; legacy `unknown` provenance cannot establish that an upgrade is active. Coordinate restart timing with all consumers before explicitly updating only the database router:
+
+```sh
+bundle exec local-development-gateway up --no-deps --force-recreate database-router
+bundle exec local-development-gateway status
+```
+
+Recreating the shared database router interrupts existing database client sessions across every consuming project/worktree. This command leaves the HTTP gateway and consumer database containers/volumes alone. If the HTTP gateway itself needs an update, separately coordinate and explicitly select `gateway` instead. Do not use `down` for a router-only update. After updating, confirm the selected service's active version is current and exercise an encrypted connection to the intended database; readiness alone is insufficient release verification.
+
 ## Worktree database services
 
 The gateway includes protocol drivers for encrypted SQL Server and PostgreSQL
@@ -133,6 +148,21 @@ substitutes for private aliases. Database cloning is independent of this
 hostname correction: it selects source/destination containers explicitly and
 connects locally.
 
+### Private database alias length
+
+The complete `${COMPOSE_PROJECT_NAME}-<database-service>` alias is one DNS label. [DNS limits each label to 63 octets](https://www.rfc-editor.org/rfc/rfc1035.html#section-2.3.4); for these ASCII names, that is 63 characters. Budget the project name against the longest database service suffix in the stack: `63 - 1 - <service-name length>`.
+
+| Database service | Appended suffix | Maximum project-name length |
+| --- | --- | ---: |
+| `db` | `-db` | 60 |
+| `db_trav_com` | `-db_trav_com` | 51 |
+
+A 60-character project name plus `-db` fits exactly; 61 characters produces a 64-character alias. With `-db_trav_com`, the corresponding boundary is 51/52 characters. These are DNS budgets, not a claim that Compose rejects oversized aliases: `docker compose config` can render an alias that exceeds the limit. Configuration rendering alone does not prove DNS resolution or database connectivity.
+
+Use the effective project name selected by [Compose's native precedence](https://docs.docker.com/compose/how-tos/project-name/): `-p`, then `COMPOSE_PROJECT_NAME`, top-level `name:`, and the directory-derived default. Inspect the rendered `name`, database aliases, and application/job/test host settings through the consumer's documented wrapper and selected Compose files. Do not implement a separate project-name resolver, truncate/hash names automatically, or change existing short identities.
+
+For a new disposable stack, explicitly choose a unique project name within the budget before creating resources. For an existing stack, changing its project name can select different project-scoped volumes and appear to lose its database. Preserve the current project identity and data; any necessary rename requires an explicit consumer-owned data migration, not an automatic gateway correction. Keep qualified aliases private and desktop gateway hostnames unchanged. The gem neither validates nor shortens consumer aliases; upgrading it does not repair an oversized name.
+
 ### Canonical development and test Compose pattern
 
 Merge these entries into the project's existing development base and gateway
@@ -294,7 +324,8 @@ retaining cancellation-aware PostgreSQL routing despite Traefik's STARTTLS suppo
 
 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.
+   `${COMPOSE_PROJECT_NAME}-<database-service>` using its existing driver setting,
+   within the [suffix-specific DNS budget](#private-database-alias-length).
 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
@@ -419,6 +450,15 @@ 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.4
+
+- Document suffix-specific DNS length budgets for private database aliases and data-safe project-name handling. No alias validation, shortening, routing, or lifecycle behavior changes.
+
+## Release 0.2.3
+
+- Status and healthy CLI reuse distinguish the installed gem version from each active shared service, reporting mismatches and unknown legacy provenance without restarting services.
+- Scoped router update instructions explain shared database session interruption and keep restart timing under caller control. Health readiness and Ruby lifecycle return values remain unchanged.
+
 ## Release 0.2.2
 
 - Canonical SQL Server/PostgreSQL Compose integration supports concurrent

data/docker-compose.yml

@@ -13,6 +13,7 @@ services:
       start_period: 1s
     labels:
       local-gateway: "true"
+      local-gateway.version: "${LOCAL_DEVELOPMENT_GATEWAY_VERSION:-unknown}"
     ports:
       - "127.0.0.1:80:80"
     restart: unless-stopped
@@ -29,7 +30,7 @@ services:
       - -I/app/lib
       - -rlocal_development_gateway
       - -e
-      - LocalDevelopmentGateway::DatabaseRouter.run
+      - File.write("/tmp/local-development-gateway-version", LocalDevelopmentGateway::VERSION); LocalDevelopmentGateway::DatabaseRouter.run
     healthcheck:
       test:
         - CMD
@@ -43,6 +44,7 @@ services:
       start_period: 1s
     labels:
       local-gateway: "true"
+      local-gateway.version: "${LOCAL_DEVELOPMENT_GATEWAY_VERSION:-unknown}"
     ports:
       - "127.0.0.1:1433:1433"
       - "127.0.0.1:5432:5432"

data/docs/architecture/local-tcp-routing.md

@@ -44,6 +44,8 @@ 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.
 
+The README's [private-alias length contract](../../README.md#private-database-alias-length) defines the DNS budget for each service suffix. Native Compose project selection and existing data identities remain authoritative; the gateway does not shorten or rename consumer projects.
+
 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

data/lib/local_development_gateway/version.rb

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

data/lib/local_development_gateway.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "open3"
+require "json"
 require "local_development_gateway/version"
 
 module LocalDevelopmentGateway
@@ -29,16 +30,16 @@ module LocalDevelopmentGateway
   end
 
   class Docker
-    def call(*args, capture: true)
+    def call(*args, capture: true, env: {})
       command = ["docker", *args]
       if capture
-        stdout, stderr, status = Open3.capture3(*command)
+        stdout, stderr, status = Open3.capture3(env, *command)
         unless status.success?
           raise DockerError.new(command, stderr.empty? ? stdout : stderr)
         end
 
         stdout
-      elsif system(*command)
+      elsif system(env, *command)
         true
       else
         raise DockerError.new(command, "")
@@ -85,7 +86,17 @@ module LocalDevelopmentGateway
     end
 
     def status
-      compose("ps", "--all")
+      output = compose("ps", "--all")
+      output << "\nInstalled gateway version: #{VERSION}\n"
+      SERVICE_NAMES.each do |service|
+        ids = gateway_container_ids(service: service, status: "running")
+        if ids.empty?
+          output << "#{service}: not running; active=unknown\n"
+        else
+          ids.each { |id| output << service_version_status(service, id) }
+        end
+      end
+      output
     end
 
     def logs(*args, follow: false)
@@ -122,12 +133,56 @@ module LocalDevelopmentGateway
         "--file",
         COMPOSE_FILE,
         *args,
-        capture: capture
+        capture: capture,
+        env: {
+          "LOCAL_DEVELOPMENT_GATEWAY_VERSION" => VERSION
+        }
       )
     end
 
     private
 
+    def service_version_status(service, id)
+      container = JSON.parse(@runner.call("inspect", id)).fetch(0)
+      if service == "database-router"
+        version = router_version(id)
+        provenance = "process-start record"
+        asset_target = "/app/lib"
+      else
+        version = container.dig("Config", "Labels", "local-gateway.version")
+        provenance = "container-creation label"
+        asset_target = "/etc/traefik/traefik.yml"
+      end
+      version = "unknown" if version.nil? || version.empty?
+      comparison = version_comparison(version)
+      mount =
+        container
+          .fetch("Mounts", [])
+          .find { |entry| entry["Destination"] == asset_target }
+      source = "unknown"
+      source = mount.fetch("Source") if mount
+      "#{service} (#{id[0, 12]}): active=#{version}; #{comparison}; " \
+        "provenance=#{provenance}; mounted assets=#{source}\n"
+    end
+
+    def router_version(id)
+      @runner.call(
+        "exec",
+        id,
+        "cat",
+        "/tmp/local-development-gateway-version"
+      ).strip
+    rescue DockerError
+      nil
+    end
+
+    def version_comparison(version)
+      return "unknown" if version == "unknown"
+      return "current" if version == VERSION
+
+      "mismatch (installed=#{VERSION}); explicit service recreation required"
+    end
+
     def wait_until_ready
       deadline = @clock.call + @timeout
       until ready?
@@ -233,7 +288,7 @@ module LocalDevelopmentGateway
 
       Commands:
         up, ensure  Start or reuse the shared gateway
-        status      Show the gateway Compose status
+        status      Show Compose status and installed/active gateway versions
         ready       Check gateway readiness
         logs        Follow gateway logs
         down, stop  Stop the gateway only when unused
@@ -260,7 +315,8 @@ module LocalDevelopmentGateway
 
       case command
       when "up", "ensure"
-        @client.ensure_running(*@argv)
+        result = @client.ensure_running(*@argv)
+        @output.write(@client.status) if result == :reused
       when "status"
         @output.write(@client.status)
       when "ready"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: local-development-gateway
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.2.4
 platform: ruby
 authors:
 - Marlen Brunner
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-14 00:00:00.000000000 Z
+date: 2026-10-22 00:00:00.000000000 Z
 dependencies: []
 description: Ruby API and CLI for starting, monitoring, and conditionally stopping
   the shared Docker gateway.