local-development-gateway 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d72f55ac50271b2247bd8eb5189f4b6c25c30a62a8cb0d451cecc38b050ea98e
-  data.tar.gz: ea4e0fda3f4f88cb39666580be77960eeab97994adfd599e3b4e2db02c96f5cc
+  metadata.gz: 6f3e2ce5cd6347553a1923006ebc26ff3ae5178e67515d6741014dc229ca115d
+  data.tar.gz: 3059913ab2b89ae89442c80112fc49701d31690b46c5ca62bf981042c765700f
 SHA512:
-  metadata.gz: 6bbf54e670547b4ff3a4b332094493ad1c825df43a50d29079b6ebfe88d85922ad6a1d73877a8de28ce22fcf2974b48db28c70250b3389d77a062a6fd14a19d9
-  data.tar.gz: 74cfbf75708d8e46a47e19ffc4a94b732e502372edfc565702c98e7ab8177e98208e543d3be45c822a6ed76bbdd83cb56bf3b50931efb334c2d3516dff4228e7
+  metadata.gz: 6190a1c1563636f2a0a6ca2a08c8acb10c0a674e24551a01cac437a02c70c766ff7f6ec81251d10c086a08f414a43c445cff09095ff5f3a57cadab3580b880d3
+  data.tar.gz: 6f04fd1c800964cb0d44e65dc792116ece3fd622cfee945f8a2d49bf7e23165bff95050422e826dad0a4f1e4497d90797c417e87f6569da639c9833c7dd98ca1

data/README.md

@@ -8,10 +8,11 @@ It lets several local projects use stable hostnames instead of competing for bro
 
 Without a gateway, two projects commonly both try to publish a web service on port `8080` and a backend service on port `3000`. Only one can start.
 
-With this gateway running, a project can publish its internal web service through a generated hostname instead:
+With this gateway running, a project routes its internal web service through a
+checkout-derived hostname instead:
 
 ```text
-http://port-35053.traditional-knowledge.localhost
+http://traditional-knowledge.localhost
                          |
                          v
 Local Development Gateway on 127.0.0.1:80
@@ -20,9 +21,13 @@ Local Development Gateway on 127.0.0.1:80
 Traditional Knowledge web container on internal port 8080
 ```
 
-`port-35053` is derived from Traditional Knowledge's generated `WEB_PORT` value. It identifies the project instance; the browser reaches the web service through the gateway on port `80`, not directly on port `35053`.
+The checkout folder identifies the project. A separately named worktree such as
+`issue-123` uses `http://issue-123.traditional-knowledge.localhost`; the browser
+reaches the web service through the gateway on port `80`, not a published
+application port.
 
-The generated hostname is a local `*.localhost` name. It resolves to loopback and does not require a public domain, external DNS provider, or internet-facing listener.
+These local `*.localhost` hostnames resolve to loopback and do not require a
+public domain, external DNS provider, or internet-facing listener.
 
 ## Start once per day
 
@@ -61,9 +66,11 @@ Consuming projects do not need a gateway checkout. Add the released gem to
 their bundle and pin the compatible minor version:
 
 ```ruby
-gem "local-development-gateway", "~> 0.1.0"
+gem "local-development-gateway", "~> 0.1"
 ```
 
+Published gem: [`local-development-gateway`](https://rubygems.org/gems/local-development-gateway)
+
 The gem packages the gateway Compose file and pinned Traefik configuration.
 Its executable provides the same lifecycle commands:
 
@@ -76,21 +83,56 @@ bundle exec local-development-gateway down
 
 `local-development-gateway` uses the installed asset path, the
 `local-gateway` Compose project and network labels, and the pinned minimum Ruby
-version declared by the gem. Upgrade the version constraint when a new
-compatible release is published. The repository's `bin/dev` is only a thin
-wrapper around this executable API.
+version declared by the gem. The `~> 0.1` constraint follows the consuming
+project's published Gemfile.
+The repository's `bin/dev` is only a thin wrapper around this executable API.
 
-## Use case: Traditional Knowledge beside WRAP
+### Ruby API lifecycle
+
+Wrap a command that needs the gateway with the block-oriented helper:
+
+```ruby
+require "local_development_gateway"
+
+result = LocalDevelopmentGateway.with_running do
+  run_development_command
+end
+```
+
+The helper starts or reuses the gateway before yielding, returns the block's
+result, and conditionally stops an unused gateway afterward. Cleanup also runs
+when the block raises without replacing the original exception. For a shutdown
+command that must not start a missing gateway, pass
+`ensure_running: false`; the block still runs and unused-gateway cleanup is
+attempted.
+
+## Development checks
+
+Install the locked development tools with `bundle install`. Run the Ruby
+formatter check and tests with:
+
+```sh
+bundle exec ruby "$(bundle show syntax_tree)/exe/stree" check \
+  Gemfile \
+  Rakefile \
+  lib/local_development_gateway.rb \
+  lib/local_development_gateway/version.rb \
+  bin/dev \
+  bin/local-development-gateway \
+  test/local_development_gateway_test.rb
+rake test
+```
 
-1. Start this gateway once.
-2. Run `dev up` in Traditional Knowledge. It writes role-based generated values to `.env.development.local`, including `WEB_PORT`, `BACKEND_PORT`, and `WEB_HOSTNAME=port-<WEB_PORT>.traditional-knowledge.localhost`.
-3. With the gateway running, Traditional Knowledge's web container joins `local-gateway`, its direct web publishing is removed, and the generated hostname routes through the gateway on `127.0.0.1:80`.
-4. Open `WEB_HOSTNAME` from `.env.development.local`.
-5. When WRAP adopts the same contract, start it normally. It can then use its own generated route labels and hostname through this same gateway.
+## Use case: Traditional Knowledge beside WRAP
 
-Each project receives an independent hostname, while the gateway owns the single browser port. The generated `WEB_PORT` is an identity seed in gateway mode, not the browser-facing port.
+1. Use the published gateway gem; it starts or reuses the shared gateway when Traditional Knowledge starts.
+2. Run `bundle install` in Traditional Knowledge so the published gateway gem is available.
+3. Run `dev up --watch` in Traditional Knowledge. The gateway is the browser entrypoint; the base checkout uses `http://traditional-knowledge.localhost`, with the API at `http://api.traditional-knowledge.localhost` and MailDev at `http://mail.traditional-knowledge.localhost`.
+4. A separately named checkout or worktree derives its own hostname, such as `http://issue-123.traditional-knowledge.localhost`. The API and MailDev hosts use the corresponding `api.` and `mail.` prefixes.
+5. Run `dev down` to stop the application services. It stops the shared gateway only when no other project is attached.
+6. When WRAP adopts the same contract, it can use its own checkout-derived hostnames through this shared gateway.
 
-Without the gateway, Traditional Knowledge publishes the same generated values directly, including `localhost:<WEB_PORT>` for the web service and `localhost:<BACKEND_PORT>` for the backend. `dev up` regenerates unavailable assignments; deleting `.env.development.local` forces a fresh assignment.
+The gateway owns the single browser port on `127.0.0.1:80`. Participating projects keep service ports internal to Docker and route browser traffic with explicit Traefik labels.
 
 ## Contract for participating projects
 
@@ -101,15 +143,7 @@ The gateway:
 - discovers only services explicitly labelled for routing;
 - has the Docker label `local-gateway=true` so a project can detect it.
 
-A participating project writes role-based generated values to its local `.env.development.local`:
-
-```dotenv
-WEB_PORT=35053
-BACKEND_PORT=38261
-WEB_HOSTNAME=port-35053.traditional-knowledge.localhost
-```
-
-With the gateway available, its web service joins `local-gateway` and supplies explicit route labels. Use a project-prefixed identifier containing the published `BACKEND_PORT` for the internal router/service name; do not generate a separate `STACK_IDENTIFIER`:
+A participating project joins routed services to `local-gateway` and supplies a checkout-derived hostname plus explicit service labels:
 
 ```yaml
 services:
@@ -120,10 +154,9 @@ services:
     labels:
       - "traefik.enable=true"
       - "traefik.docker.network=local-gateway"
-      - "traefik.http.routers.<project>-<backend-port>.rule=Host(`<web-hostname>`)"
-      - "traefik.http.routers.<project>-<backend-port>.entrypoints=web"
-      - "traefik.http.routers.<project>-<backend-port>.service=<project>-<backend-port>"
-      - "traefik.http.services.<project>-<backend-port>.loadbalancer.server.port=8080"
+      - "traefik.http.routers.<compose-project>-web.rule=Host(`<web-hostname>`)"
+      - "traefik.http.routers.<compose-project>-web.entrypoints=web"
+      - "traefik.http.services.<compose-project>-web.loadbalancer.server.port=8080"
 
 networks:
   local-gateway:
@@ -131,19 +164,9 @@ networks:
     name: local-gateway
 ```
 
-Without the gateway, publish the same generated values directly:
-
-```yaml
-services:
-  web:
-    ports:
-      - "127.0.0.1:${WEB_PORT}:8080"
-  backend:
-    ports:
-      - "127.0.0.1:${BACKEND_PORT}:3000"
-```
+Use a project- and service-prefixed router/service identifier. Never derive a destination port from the hostname; each routed service must name one explicit internal destination port.
 
-Use a unique generated `WEB_PORT` and `BACKEND_PORT` for every running project instance. Never derive a destination port from the hostname; each route must name one explicit Docker service and internal port.
+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.
 
 ## Authentication callbacks
 

data/lib/local_development_gateway/version.rb

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

data/lib/local_development_gateway.rb

@@ -12,7 +12,8 @@ module LocalDevelopmentGateway
   COMPOSE_FILE = File.join(ASSET_ROOT, "docker-compose.yml")
   TRAEFIK_CONFIG_FILE = File.join(ASSET_ROOT, "config", "traefik.yml")
 
-  class Error < StandardError; end
+  class Error < StandardError
+  end
 
   class DockerError < Error
     attr_reader :command, :output
@@ -29,7 +30,9 @@ module LocalDevelopmentGateway
       command = ["docker", *args]
       if capture
         stdout, stderr, status = Open3.capture3(*command)
-        raise DockerError.new(command, stderr.empty? ? stdout : stderr) unless status.success?
+        unless status.success?
+          raise DockerError.new(command, stderr.empty? ? stdout : stderr)
+        end
 
         stdout
       elsif system(*command)
@@ -41,7 +44,8 @@ module LocalDevelopmentGateway
   end
 
   class Client
-    CONTAINER_FORMAT = "{{.ID}}\t{{.Label \"com.docker.compose.project\"}}\t{{.Label \"com.docker.compose.service\"}}\t{{.Label \"local-gateway\"}}"
+    CONTAINER_FORMAT =
+      "{{.ID}}\t{{.Label \"com.docker.compose.project\"}}\t{{.Label \"com.docker.compose.service\"}}\t{{.Label \"local-gateway\"}}"
 
     def initialize(
       runner: Docker.new,
@@ -68,7 +72,10 @@ module LocalDevelopmentGateway
     alias start ensure_running
 
     def ready?
-      network_exists? && gateway_container_ids(status: "running").any? { |id| healthy_container?(id) }
+      network_exists? &&
+        gateway_container_ids(status: "running").any? do |id|
+          healthy_container?(id)
+        end
     end
 
     def status
@@ -87,13 +94,29 @@ module LocalDevelopmentGateway
       :stopped
     end
 
+    def with_running(ensure_running: true)
+      begin
+        self.ensure_running if ensure_running
+        yield
+      ensure
+        block_error = $!
+        begin
+          stop_if_unused
+        rescue StandardError => cleanup_error
+          raise cleanup_error unless block_error
+        end
+      end
+    end
+
     def compose(*args, capture: true)
       @runner.call(
         "compose",
-        "--project-name", PROJECT_NAME,
-        "--file", COMPOSE_FILE,
+        "--project-name",
+        PROJECT_NAME,
+        "--file",
+        COMPOSE_FILE,
         *args,
-        capture: capture,
+        capture: capture
       )
     end
 
@@ -102,21 +125,26 @@ module LocalDevelopmentGateway
     def wait_until_ready
       deadline = @clock.call + @timeout
       until ready?
-        raise Error, "Local Development Gateway did not become ready" if @clock.call >= deadline
+        if @clock.call >= deadline
+          raise Error, "Local Development Gateway did not become ready"
+        end
 
         @sleeper.call(@poll_interval)
       end
     end
 
     def network_exists?
-      labels = @runner.call(
-        "network",
-        "inspect",
-        NETWORK_NAME,
-        "--format",
-        "{{index .Labels \"com.docker.compose.project\"}}\t{{index .Labels \"com.docker.compose.network\"}}",
-      )
-      labels.lines.any? { |line| line.strip == "#{PROJECT_NAME}\t#{NETWORK_NAME}" }
+      labels =
+        @runner.call(
+          "network",
+          "inspect",
+          NETWORK_NAME,
+          "--format",
+          "{{index .Labels \"com.docker.compose.project\"}}\t{{index .Labels \"com.docker.compose.network\"}}"
+        )
+      labels.lines.any? do |line|
+        line.strip == "#{PROJECT_NAME}\t#{NETWORK_NAME}"
+      end
     rescue DockerError
       false
     end
@@ -128,30 +156,44 @@ module LocalDevelopmentGateway
     def gateway_container_ids(status: nil)
       args = ["ps"]
       args << "--all" unless status
-      args.concat([
-        "--filter", "network=#{NETWORK_NAME}",
-        "--filter", "label=com.docker.compose.project=#{PROJECT_NAME}",
-        "--filter", "label=com.docker.compose.service=#{SERVICE_NAME}",
-        "--filter", "label=#{GATEWAY_LABEL}=true",
-      ])
+      args.concat(
+        [
+          "--filter",
+          "network=#{NETWORK_NAME}",
+          "--filter",
+          "label=com.docker.compose.project=#{PROJECT_NAME}",
+          "--filter",
+          "label=com.docker.compose.service=#{SERVICE_NAME}",
+          "--filter",
+          "label=#{GATEWAY_LABEL}=true"
+        ]
+      )
       args.push("--filter", "status=#{status}") if status
       output = @runner.call(*args, "--quiet")
       output.lines.map(&:strip).reject(&:empty?)
     end
 
     def healthy_container?(id)
-      @runner.call("inspect", "--format", "{{.State.Health.Status}}", id).strip == "healthy"
+      @runner.call(
+        "inspect",
+        "--format",
+        "{{.State.Health.Status}}",
+        id
+      ).strip == "healthy"
     rescue DockerError
       false
     end
 
     def attached_containers
-      output = @runner.call(
-        "ps",
-        "--all",
-        "--filter", "network=#{NETWORK_NAME}",
-        "--format", CONTAINER_FORMAT,
-      )
+      output =
+        @runner.call(
+          "ps",
+          "--all",
+          "--filter",
+          "network=#{NETWORK_NAME}",
+          "--format",
+          CONTAINER_FORMAT
+        )
       output.lines.filter_map do |line|
         id, project, service, label = line.strip.split("\t", -1)
         next if id.nil? || id.empty?
@@ -161,15 +203,12 @@ module LocalDevelopmentGateway
     end
 
     def non_gateway_containers_attached?
-      attached_containers.any? do |container|
-        !gateway_container?(container)
-      end
+      attached_containers.any? { |container| !gateway_container?(container) }
     end
 
     def gateway_container?(container)
       container[:project] == PROJECT_NAME &&
-        container[:service] == SERVICE_NAME &&
-        container[:label] == "true"
+        container[:service] == SERVICE_NAME && container[:label] == "true"
     end
   end
 
@@ -200,7 +239,9 @@ module LocalDevelopmentGateway
 
     def run
       command = @argv.shift
-      return print_usage(0) if command.nil? || %w[help --help -h].include?(command)
+      if command.nil? || %w[help --help -h].include?(command)
+        return print_usage(0)
+      end
 
       case command
       when "up", "ensure"
@@ -235,8 +276,9 @@ module LocalDevelopmentGateway
     def report_stop(result)
       messages = {
         not_running: "Local Development Gateway is not running",
-        in_use: "Leaving Local Development Gateway running because another container is attached",
-        stopped: "Stopped Local Development Gateway",
+        in_use:
+          "Leaving Local Development Gateway running because another container is attached",
+        stopped: "Stopped Local Development Gateway"
       }
       @output.puts messages.fetch(result)
     end
@@ -247,6 +289,10 @@ module LocalDevelopmentGateway
       Client.new.ensure_running(*args)
     end
 
+    def with_running(ensure_running: true, &block)
+      Client.new.with_running(ensure_running: ensure_running, &block)
+    end
+
     def start(*args)
       ensure_running(*args)
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: local-development-gateway
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Marlen Brunner