local-development-gateway 0.2.3 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: c8606a508df46ba2018a8cd768c86e6a41ce38a5ef7caedff7c5832017d34e38
4
- data.tar.gz: ebd5a8310bcb5b235d0c00c717813873b73e6061d6333f89ba188818636b3162
3
+ metadata.gz: e7a28d928bf046ed735f00c3148307fb14c14d441b1cbc28e1d8d1014afc2855
4
+ data.tar.gz: fddfd6b3c2a1bae60dfb46e03531ee13988b0e697a69839566c006a3d92a709d
5
5
  SHA512:
6
- metadata.gz: cb84da27199e8af6e78189f9025240ae090ae84372e3ccbd3f1d25240e18a4710a3eb16f32793b2e1411bc0bb9d9f0535f9a4ff5955815cc1b0eda322680fdd8
7
- data.tar.gz: e0e3a2a24e3f039d516a150496b37527ff98d6549aafaeeb0aca5b36116f68ed24bb5f3948c35ab3555efeca1c40267d334f233d50a46aa7dbf55c50333b62e5
6
+ metadata.gz: c7a84ed03db0ff434696c91d461dade6aea0cdecb8a7eda37558456936a6520cae74cb2baf5a4af59682d6976c5fe7672d1d767b28c63e5a00c2fe3b695d3e53
7
+ data.tar.gz: 8b0278d4f9899ab6527c9de01f87335c3a068d17341f03ba53fa7b0186e28bdbabadb9ab303bdee6ca88f7faa6d0409864f50e84891b3cfae04e34d837db12d0
data/README.md CHANGED
@@ -66,7 +66,7 @@ Consuming projects do not need a gateway checkout. Add the released gem to
66
66
  their bundle and pin the compatible minor version:
67
67
 
68
68
  ```ruby
69
- gem "local-development-gateway", "~> 0.2"
69
+ gem "local-development-gateway", "~> 0.3.0"
70
70
  ```
71
71
 
72
72
  Published gem: [`local-development-gateway`](https://rubygems.org/gems/local-development-gateway)
@@ -83,8 +83,7 @@ bundle exec local-development-gateway down
83
83
 
84
84
  `local-development-gateway` uses the installed asset path, the
85
85
  `local-gateway` Compose project and network labels, and the pinned minimum Ruby
86
- version declared by the gem. The `~> 0.2` constraint follows the consuming
87
- project's published Gemfile.
86
+ version declared by the gem. Use `~> 0.3.0` for the private database alias API below.
88
87
  The repository's `bin/dev` is only a thin wrapper around this executable API.
89
88
 
90
89
  ### Ruby API lifecycle
@@ -131,7 +130,7 @@ connections. No host agent, DNS server, administrator privileges, or
131
130
 
132
131
  | Caller | Database hostname | Routing |
133
132
  | --- | --- | --- |
134
- | Application/API, background job, test container | `${COMPOSE_PROJECT_NAME}-<database-service>` | Qualified alias on that checkout's private `default` network; internal database port |
133
+ | Application/API, background job, test container | `LocalDevelopmentGateway.database_alias(project_name:, service_name:)` | Qualified alias on that checkout's private `default` network; internal database port |
135
134
  | Desktop client, such as DBeaver | `db.<worktree>.<project>.localhost` | Encrypted, hostname-labelled gateway endpoint on loopback |
136
135
  | Database-local console, backup, clone command | `localhost` | Explicitly select the intended database container first |
137
136
 
@@ -148,6 +147,63 @@ substitutes for private aliases. Database cloning is independent of this
148
147
  hostname correction: it selects source/destination containers explicitly and
149
148
  connects locally.
150
149
 
150
+ ### Private database alias length
151
+
152
+ The complete `<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). Starting in 0.3.0, consumers can opt into a deterministic private alias without renaming their Compose project or its volumes:
153
+
154
+ ```ruby
155
+ require "local_development_gateway"
156
+
157
+ LocalDevelopmentGateway.database_alias(
158
+ project_name: "issue-123-example",
159
+ service_name: "db_trav_com"
160
+ )
161
+ # => "issue-123-example-db_trav_com"
162
+ ```
163
+
164
+ The pure public function preserves the **entire** `<project-name>-<service-name>` string when it fits, including an exact 63-byte fit. A 60-character project plus `-db` fits; 61 characters needs shortening. For `-db_trav_com`, the corresponding boundary is 51/52 characters. Longer aliases become the first 38 characters of the full alias, a hyphen, and the first 24 hexadecimal characters of SHA256 over `project_name + "\0" + service_name`. The NUL separator distinguishes identities whose hyphen-joined forms could otherwise be ambiguous. The 96-bit digest suffix provides collision resistance, not a mathematical guarantee that collisions are impossible. No persistent or random state is involved.
165
+
166
+ Inputs must be nonempty ASCII strings. Project names start with a lowercase letter or digit and otherwise contain lowercase letters, digits, hyphens, or underscores. Service names start with an ASCII letter or digit and otherwise contain ASCII letters, digits, hyphens, or underscores; case is preserved. Legacy underscores remain supported, even though they are not strict DNS hostname characters. Invalid inputs raise `ArgumentError`; the API does not normalize names.
167
+
168
+ Use the effective project name selected by [Compose's native precedence](https://docs.docker.com/compose/how-tos/project-name/): `-p`/`--project-name`, then `COMPOSE_PROJECT_NAME`, top-level `name:`, and directory defaults (including native file/project-directory selection). Compose remains the identity owner: ask its ordinary `config --format json` output for `name`, rather than implementing a separate resolver or parsing `.env`. Do not use `--no-interpolate` for identity discovery; it does not reliably resolve interpolated top-level names.
169
+
170
+ Derive each database alias from that name and its service name, then use the identical value for the private network alias and every matching application/job/test host setting. Preserve project names, volumes, images, credentials, database names, and desktop gateway hostnames. Upgrading the gem alone does not repair unchanged consumers: their wrappers and Compose configuration must adopt the API, then recreate only their affected database/client containers. This private-alias adoption does **not** require restarting the shared gateway or database router.
171
+
172
+ ### Runnable disposable consumer example
173
+
174
+ [`examples/database-aliases`](examples/database-aliases) supplies real base and gateway-overlay Compose files and a small Ruby wrapper. This is an adoption example, not a downstream rollout or a replacement for a consumer's existing driver configuration, images, data, or lifecycle wrapper. Both databases use PostgreSQL to demonstrate distinct services with the same driver; `api`/`jobs` select `app_data` on `db`, while `test_api` selects `test_data` with separate credentials on `db_trav_com`. The development-only credentials must not be reused outside this disposable stack. No database publishes host ports.
175
+
176
+ Run from `examples/database-aliases`. With the 0.3.0 gem available in your bundle, use `bundle exec ruby compose.rb`; with a compatible gem installed outside Bundler, use `ruby compose.rb`. To exercise this repository's source instead, use `bundle exec ruby -I../../lib compose.rb`. The command shape is:
177
+
178
+ ```text
179
+ ruby compose.rb [native Compose global options] -- COMMAND [args]
180
+ ```
181
+
182
+ Only the `--` delimiter is interpreted by the wrapper. Put native global options such as `-p`, `--project-name`, `--project-directory`, `--env-file`, `--profile`, and `-f` before it; put the Compose command and its arguments after it. With no globals, Compose uses its normal environment and defaults. Keep the same globals/environment for subsequent lifecycle commands so they select the same resources.
183
+
184
+ ```sh
185
+ # Base-only: Compose chooses the project identity; only the databases start.
186
+ bundle exec ruby compose.rb -- config
187
+ bundle exec ruby compose.rb -- up -d --wait
188
+ bundle exec ruby compose.rb -- run --rm api psql -c 'SELECT current_database(), current_user, inet_server_addr()'
189
+ bundle exec ruby compose.rb -- run --rm jobs psql -c 'SELECT current_database(), current_user, inet_server_addr()'
190
+ bundle exec ruby compose.rb -- run --rm test_api psql -c 'SELECT current_database(), current_user, inet_server_addr()'
191
+ bundle exec ruby compose.rb -- down
192
+
193
+ # Optional overlay: the shared gateway/network must already be available.
194
+ # Choose a unique checkout-derived desktop hostname; do not change an existing
195
+ # stack's project identity just to shorten its aliases.
196
+ export GATEWAY_HOSTNAME=issue-123.database-aliases.localhost
197
+ bundle exec ruby compose.rb -f compose.yml -f gateway.yml -- config
198
+ bundle exec ruby compose.rb -f compose.yml -f gateway.yml -- up -d --wait
199
+ bundle exec ruby compose.rb -f compose.yml -f gateway.yml -- run --rm api psql -c 'SELECT current_database()'
200
+ bundle exec ruby compose.rb -f compose.yml -f gateway.yml -- down
201
+ ```
202
+
203
+ Clients are in the `clients` profile so ordinary `up --wait` remains database-only; `run` explicitly selects each client. To keep clients running for `exec` checks, add `--profile clients` before `--`. The overlay attaches databases and all clients to shared ingress while preserving their mapping-form private networks. Desktop routes are `db.${GATEWAY_HOSTNAME}` and `secondary-db.${GATEWAY_HOSTNAME}` on port 5432 with SSL mode `require` and SNI; container clients still use private aliases and internal port 5432.
204
+
205
+ The wrapper first renders `docker compose [exact globals] config --format json` with discovery-only `DB_HOST`/`DB_TRAV_COM_HOST` placeholders. It never starts that configuration. After reading the native `name`, it execs the requested command with derived aliases and the exact same globals, files, and inherited environment. It does not force a project name, change `COMPOSE_PROJECT_NAME`, or read `.env` itself. Keep project identity independent of these two host variables; they are reserved wrapper outputs. Configuration errors stop execution. Direct Compose invocation without those variables fails closed through `${DB_HOST:?run compose.rb}` and `${DB_TRAV_COM_HOST:?run compose.rb}`. Named volumes survive `down`; use `down -v` through the same wrapper/options only when deliberately discarding this example's disposable data. None of these commands mutates or restarts the shared gateway.
206
+
151
207
  ### Canonical development and test Compose pattern
152
208
 
153
209
  Merge these entries into the project's existing development base and gateway
@@ -157,44 +213,39 @@ existing configuration keys: `AZURE_SQL_HOST` is a SQL Server application
157
213
  example; `PGHOST` is the PostgreSQL/libpq equivalent. An application with a
158
214
  different PostgreSQL configuration key must set that key instead.
159
215
 
160
- For example, a wrapper-derived `COMPOSE_PROJECT_NAME=issue-123-example` gives
161
- private hosts `issue-123-example-db` and `issue-123-example-db_trav_com`.
162
- `GATEWAY_HOSTNAME=issue-123.example.localhost` separately identifies desktop
163
- routes. This requires no new Ruby API, generic database environment variable,
164
- or consumer runtime.
216
+ For example, an effective Compose project name `issue-123-example` gives private hosts `issue-123-example-db` and `issue-123-example-db_trav_com`. Have the consumer wrapper export the API results as `DB_HOST` and `DB_TRAV_COM_HOST` for interpolation below. These are wrapper variables, not new application driver settings. `GATEWAY_HOSTNAME=issue-123.example.localhost` separately identifies desktop routes.
165
217
 
166
218
  ```yaml
167
219
  # docker-compose.development.yml: also safe without the gateway overlay.
168
220
  services:
169
221
  api:
170
222
  environment:
171
- AZURE_SQL_HOST: "${COMPOSE_PROJECT_NAME}-db"
172
- PGHOST: "${COMPOSE_PROJECT_NAME}-db_trav_com"
223
+ AZURE_SQL_HOST: "${DB_HOST:?derive with database_alias}"
224
+ PGHOST: "${DB_TRAV_COM_HOST:?derive with database_alias}"
173
225
  jobs:
174
226
  environment:
175
- AZURE_SQL_HOST: "${COMPOSE_PROJECT_NAME}-db"
176
- PGHOST: "${COMPOSE_PROJECT_NAME}-db_trav_com"
227
+ AZURE_SQL_HOST: "${DB_HOST:?derive with database_alias}"
228
+ PGHOST: "${DB_TRAV_COM_HOST:?derive with database_alias}"
177
229
  test_api:
178
230
  environment:
179
- AZURE_SQL_HOST: "${COMPOSE_PROJECT_NAME}-db"
180
- PGHOST: "${COMPOSE_PROJECT_NAME}-db_trav_com"
231
+ AZURE_SQL_HOST: "${DB_HOST:?derive with database_alias}"
232
+ PGHOST: "${DB_TRAV_COM_HOST:?derive with database_alias}"
181
233
  db:
182
234
  networks:
183
235
  default:
184
236
  aliases:
185
- - "${COMPOSE_PROJECT_NAME}-db"
237
+ - "${DB_HOST:?derive with database_alias}"
186
238
  db_trav_com:
187
239
  networks:
188
240
  default:
189
241
  aliases:
190
- - "${COMPOSE_PROJECT_NAME}-db_trav_com"
242
+ - "${DB_TRAV_COM_HOST:?derive with database_alias}"
191
243
  ```
192
244
 
193
245
  The example's driver assignments are illustrative. In
194
246
  [Travel Authorization's overlay](https://github.com/icefoganalytics/travel-authorization/blob/main/docker-compose.development.gateway.yml),
195
247
  `db` is PostgreSQL and `db_trav_com` is SQL Server: its PostgreSQL host setting
196
- must use `${COMPOSE_PROJECT_NAME}-db`, and its SQL Server host setting must use
197
- `${COMPOSE_PROJECT_NAME}-db_trav_com`, with labels/ports matching those drivers.
248
+ must use the alias derived for `db`, and its SQL Server host setting must use the alias derived for `db_trav_com`, with labels/ports matching those drivers.
198
249
  Apply the rule separately to **every** database service, even when two services
199
250
  use the same driver. Preserve each context's existing credentials, internal
200
251
  port, and database name; tests must still select the test database rather than
@@ -307,9 +358,7 @@ retaining cancellation-aware PostgreSQL routing despite Traefik's STARTTLS suppo
307
358
 
308
359
  ### Downstream adoption checklist
309
360
 
310
- 1. Give each concurrent checkout a distinct Compose project name and desktop
311
- route hostname. Qualify every API/job/test database host with
312
- `${COMPOSE_PROJECT_NAME}-<database-service>` using its existing driver setting.
361
+ 1. Give each concurrent checkout a distinct Compose project name and desktop route hostname. Derive each private alias from the native effective project name and database service with [`database_alias`](#private-database-alias-length), then set every matching API/job/test driver host. Do not rename an existing project or volumes to fit a DNS budget.
313
362
  2. Advertise each qualified alias only on its private `default` network;
314
363
  preserve it through mapping-form network merges in base-only and gateway modes.
315
364
  3. Remove fixed database publications from development/test stacks; retain
@@ -330,14 +379,15 @@ prevent an attached, malicious container from connecting to another database.
330
379
 
331
380
  ## Development checks
332
381
 
333
- Install the locked development tools with `bundle install`. Run the Ruby
334
- formatter check and tests with:
382
+ Install the locked development tools with `bundle install`. Ruby lint uses RuboCop's non-fixing `Lint` checks; Syntax Tree owns formatting. These checks run on the host, like the existing Ruby tests: `bin/dev` controls the shared gateway, not a test or lint container. `.omp-verifier.json` declares that native lint command explicitly.
335
383
 
336
384
  ```sh
385
+ bundle exec rubocop --lint
337
386
  bundle exec ruby "$(bundle show syntax_tree)/exe/stree" check \
338
387
  Gemfile \
339
388
  Rakefile \
340
389
  lib/local_development_gateway.rb \
390
+ lib/local_development_gateway/database_alias.rb \
341
391
  lib/local_development_gateway/database_router.rb \
342
392
  lib/local_development_gateway/database_router/*.rb \
343
393
  lib/local_development_gateway/database_router/drivers/*.rb \
@@ -346,6 +396,7 @@ bundle exec ruby "$(bundle show syntax_tree)/exe/stree" check \
346
396
  lib/local_development_gateway/version.rb \
347
397
  bin/dev \
348
398
  bin/local-development-gateway \
399
+ examples/database-aliases/compose.rb \
349
400
  test/*.rb \
350
401
  test/database_router/*.rb \
351
402
  test/database_router/drivers/*.rb \
@@ -434,6 +485,15 @@ It mounts the Docker socket so it can discover labelled containers. A read-only
434
485
  | A project uses normal ports unexpectedly | Confirm the gateway container is running and has `local-gateway=true`. |
435
486
  | Authentication rejects the callback | Confirm the generated hostname matches the allowed wildcard callback pattern. |
436
487
 
488
+ ## Release 0.3.0
489
+
490
+ - Add the opt-in `LocalDevelopmentGateway.database_alias(project_name:, service_name:)` API: preserve short/exact-fit identities and deterministically shorten long private aliases with a 96-bit SHA256 suffix.
491
+ - Document native Compose identity discovery and provide a disposable multi-database consumer example for base-only and gateway modes. Existing consumer configuration is not rewritten; no shared gateway restart or project/volume rename is required.
492
+
493
+ ## Release 0.2.4
494
+
495
+ - 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.
496
+
437
497
  ## Release 0.2.3
438
498
 
439
499
  - Status and healthy CLI reuse distinguish the installed gem version from each active shared service, reporting mismatches and unknown legacy provenance without restarting services.
@@ -33,7 +33,7 @@ PostgreSQL base/overlay examples live in the README's
33
33
 
34
34
  | Connection path | Destination selection |
35
35
  | --- | --- |
36
- | API, background job, test | `${COMPOSE_PROJECT_NAME}-<database-service>` on private Docker DNS, using the driver's existing host setting and internal port |
36
+ | API, background job, test | Private qualified alias from `LocalDevelopmentGateway.database_alias(project_name:, service_name:)`, using the driver's existing host setting and internal port |
37
37
  | Desktop database client | Encrypted `db.<worktree>.<project>.localhost` endpoint; driver/hostname labels select the backend |
38
38
  | Database-local console, backup, clone | Explicitly selected container, then `localhost`; not gateway routing |
39
39
 
@@ -44,6 +44,8 @@ preserves `default.aliases`. Configure all application/job/test contexts with
44
44
  their appropriate aliases, existing credentials, and intended database names;
45
45
  test contexts still select their own test database.
46
46
 
47
+ The README's [private-alias length contract](../../README.md#private-database-alias-length) defines the opt-in 0.3.0 API: preserve full aliases through 63 bytes, otherwise retain a 38-character prefix and append a 96-bit SHA256 suffix over the NUL-separated project/service identity. Native Compose project selection and existing data identities remain authoritative; only private aliases shorten, never project names or volumes. Consumers must adopt the derived aliases in their own configuration; a gem upgrade alone does not repair them, and adoption requires no shared router restart.
48
+
47
49
  Gateway-mode development and test stacks publish no database host ports.
48
50
  Container consumers work with the base alone. Desktop access without the
49
51
  gateway is an explicit project-local port-publishing overlay, not an inherited
@@ -57,14 +59,14 @@ the internal hostname correction.
57
59
 
58
60
  Requirements:
59
61
 
60
- - No consumer Ruby API calls.
62
+ - No consumer Ruby API calls for desktop routing; long private aliases may opt into the pure alias helper through an existing wrapper.
61
63
  - No consumer-side address allocator.
62
64
  - No per-worktree host-port selection.
63
65
  - No bind-address environment variable passed from application code.
64
66
  - No consumer startup or shutdown hook solely for gateway routing.
65
67
  - No consumer cleanup call.
66
68
  - No manually maintained DBeaver port per worktree.
67
- - The consumer supplies only declarative service identity and internal-port metadata.
69
+ - Desktop routing requires only declarative service identity and internal-port metadata.
68
70
 
69
71
  - No administrator or root installation.
70
72
  - No host `/etc/hosts`, DNS, resolver, systemd, or Windows-service changes.
@@ -277,13 +279,11 @@ instead of sharing a generic fixture layer.
277
279
  7. Stop A; A's route disappears while B remains available.
278
280
  8. Verify existing HTTP hostnames still use Traefik.
279
281
  9. Verify every host listener is loopback-only.
280
- 10. Demonstrate consumer integration as a Compose-only diff.
282
+ 10. Demonstrate desktop routing integration as a Compose-only diff; private alias adoption may additionally call the pure alias helper from the consumer wrapper.
281
283
 
282
284
  ## Non-Goals
283
285
 
284
- - Changing consumer application code, adding new development wrapper runtimes,
285
- or automatically mutating consumer networks. Existing Compose connection
286
- settings and file selection must adopt the documented contract.
286
+ - Automatically changing consumer application code, adding new development wrapper runtimes, or mutating consumer networks. Existing wrappers can opt into the pure alias API; their Compose connection settings and file selection must adopt the documented contract.
287
287
  - Requiring consumers to run DNS, a proxy, or host installation.
288
288
  - Assigning a different database port to each worktree.
289
289
  - Publishing development routes outside the machine.
@@ -0,0 +1,41 @@
1
+ #!/usr/bin/env ruby
2
+
3
+ require "local_development_gateway"
4
+ require "open3"
5
+ require "json"
6
+
7
+ delimiter = ARGV.index("--")
8
+ unless delimiter && delimiter < ARGV.length - 1
9
+ abort "Usage: ruby compose.rb [native Compose global options] -- COMMAND [args]"
10
+ end
11
+
12
+ global_options = ARGV.take(delimiter)
13
+ command = ARGV.drop(delimiter + 1)
14
+ compose = ["docker", "compose", *global_options]
15
+ discovery_environment = {
16
+ "DB_HOST" => "alias-discovery-only",
17
+ "DB_TRAV_COM_HOST" => "alias-discovery-only"
18
+ }
19
+
20
+ # Render only: never create services with discovery placeholders. Compose owns
21
+ # project-name precedence, file selection, interpolation, and directory defaults.
22
+ configuration, diagnostics, status =
23
+ Open3.capture3(discovery_environment, *compose, "config", "--format", "json")
24
+ $stderr.write(diagnostics)
25
+ exit(status.exitstatus || 1) unless status.success?
26
+
27
+ project_name = JSON.parse(configuration).fetch("name")
28
+ host_environment = {
29
+ "DB_HOST" =>
30
+ LocalDevelopmentGateway.database_alias(
31
+ project_name: project_name,
32
+ service_name: "db"
33
+ ),
34
+ "DB_TRAV_COM_HOST" =>
35
+ LocalDevelopmentGateway.database_alias(
36
+ project_name: project_name,
37
+ service_name: "db_trav_com"
38
+ )
39
+ }
40
+
41
+ exec(host_environment, *compose, *command)
@@ -0,0 +1,81 @@
1
+ services:
2
+ db:
3
+ image: postgres:17-alpine
4
+ hostname: primary-db
5
+ environment:
6
+ POSTGRES_USER: example
7
+ POSTGRES_PASSWORD: development-only
8
+ POSTGRES_DB: app_data
9
+ volumes:
10
+ - primary-data:/var/lib/postgresql/data
11
+ networks:
12
+ default:
13
+ aliases:
14
+ - "${DB_HOST:?run compose.rb}"
15
+ healthcheck:
16
+ test: ["CMD-SHELL", "pg_isready -U example -d app_data"]
17
+ interval: 2s
18
+ timeout: 2s
19
+ retries: 30
20
+
21
+ db_trav_com:
22
+ image: postgres:17-alpine
23
+ hostname: secondary-db
24
+ environment:
25
+ POSTGRES_USER: test_example
26
+ POSTGRES_PASSWORD: test-development-only
27
+ POSTGRES_DB: test_data
28
+ volumes:
29
+ - secondary-data:/var/lib/postgresql/data
30
+ networks:
31
+ default:
32
+ aliases:
33
+ - "${DB_TRAV_COM_HOST:?run compose.rb}"
34
+ healthcheck:
35
+ test: ["CMD-SHELL", "pg_isready -U test_example -d test_data"]
36
+ interval: 2s
37
+ timeout: 2s
38
+ retries: 30
39
+
40
+ api:
41
+ image: postgres:17-alpine
42
+ profiles: [clients]
43
+ command: ["sleep", "infinity"]
44
+ environment:
45
+ PGHOST: "${DB_HOST:?run compose.rb}"
46
+ PGPORT: "5432"
47
+ PGUSER: example
48
+ PGPASSWORD: development-only
49
+ PGDATABASE: app_data
50
+ networks:
51
+ default: {}
52
+
53
+ jobs:
54
+ image: postgres:17-alpine
55
+ profiles: [clients]
56
+ command: ["sleep", "infinity"]
57
+ environment:
58
+ PGHOST: "${DB_HOST:?run compose.rb}"
59
+ PGPORT: "5432"
60
+ PGUSER: example
61
+ PGPASSWORD: development-only
62
+ PGDATABASE: app_data
63
+ networks:
64
+ default: {}
65
+
66
+ test_api:
67
+ image: postgres:17-alpine
68
+ profiles: [clients]
69
+ command: ["sleep", "infinity"]
70
+ environment:
71
+ PGHOST: "${DB_TRAV_COM_HOST:?run compose.rb}"
72
+ PGPORT: "5432"
73
+ PGUSER: test_example
74
+ PGPASSWORD: test-development-only
75
+ PGDATABASE: test_data
76
+ networks:
77
+ default: {}
78
+
79
+ volumes:
80
+ primary-data: {}
81
+ secondary-data: {}
@@ -0,0 +1,38 @@
1
+ services:
2
+ db:
3
+ networks:
4
+ default: {}
5
+ local-gateway: {}
6
+ labels:
7
+ local-gateway.tcp.driver: postgresql
8
+ local-gateway.tcp.hostname: "db.${GATEWAY_HOSTNAME:?set a unique checkout-derived GATEWAY_HOSTNAME}"
9
+ local-gateway.tcp.port: "5432"
10
+
11
+ db_trav_com:
12
+ networks:
13
+ default: {}
14
+ local-gateway: {}
15
+ labels:
16
+ local-gateway.tcp.driver: postgresql
17
+ local-gateway.tcp.hostname: "secondary-db.${GATEWAY_HOSTNAME:?set a unique checkout-derived GATEWAY_HOSTNAME}"
18
+ local-gateway.tcp.port: "5432"
19
+
20
+ api:
21
+ networks:
22
+ default: {}
23
+ local-gateway: {}
24
+
25
+ jobs:
26
+ networks:
27
+ default: {}
28
+ local-gateway: {}
29
+
30
+ test_api:
31
+ networks:
32
+ default: {}
33
+ local-gateway: {}
34
+
35
+ networks:
36
+ local-gateway:
37
+ external: true
38
+ name: local-gateway
@@ -0,0 +1,27 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "digest"
4
+
5
+ module LocalDevelopmentGateway
6
+ def self.database_alias(project_name:, service_name:)
7
+ unless project_name.is_a?(String) && project_name.ascii_only? &&
8
+ /\A[a-z0-9][a-z0-9_-]*\z/.match?(project_name)
9
+ raise ArgumentError,
10
+ "project_name must be a nonempty lowercase ASCII Compose project name"
11
+ end
12
+
13
+ unless service_name.is_a?(String) && service_name.ascii_only? &&
14
+ /\A[A-Za-z0-9][A-Za-z0-9_-]*\z/.match?(service_name)
15
+ raise ArgumentError,
16
+ "service_name must be a nonempty ASCII Compose service name"
17
+ end
18
+
19
+ full_alias = "#{project_name}-#{service_name}"
20
+ return full_alias if full_alias.bytesize <= 63
21
+
22
+ # Permanent derivation: retain 38 characters plus a 96-bit SHA256 suffix.
23
+ # NUL separates the original names so different partitions hash differently.
24
+ suffix = Digest::SHA256.hexdigest("#{project_name}\0#{service_name}")[0, 24]
25
+ "#{full_alias[0, 38]}-#{suffix}"
26
+ end
27
+ end
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module LocalDevelopmentGateway
4
- VERSION = "0.2.3"
4
+ VERSION = "0.3.0"
5
5
  end
@@ -3,6 +3,7 @@
3
3
  require "open3"
4
4
  require "json"
5
5
  require "local_development_gateway/version"
6
+ require "local_development_gateway/database_alias"
6
7
 
7
8
  module LocalDevelopmentGateway
8
9
  PROJECT_NAME = "local-gateway"
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: local-development-gateway
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.2.3
4
+ version: 0.3.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Marlen Brunner
8
8
  autorequire:
9
9
  bindir: bin
10
10
  cert_chain: []
11
- date: 2026-10-22 00:00:00.000000000 Z
11
+ date: 2026-11-16 00:00:00.000000000 Z
12
12
  dependencies: []
13
13
  description: Ruby API and CLI for starting, monitoring, and conditionally stopping
14
14
  the shared Docker gateway.
@@ -24,7 +24,11 @@ files:
24
24
  - config/traefik.yml
25
25
  - docker-compose.yml
26
26
  - docs/architecture/local-tcp-routing.md
27
+ - examples/database-aliases/compose.rb
28
+ - examples/database-aliases/compose.yml
29
+ - examples/database-aliases/gateway.yml
27
30
  - lib/local_development_gateway.rb
31
+ - lib/local_development_gateway/database_alias.rb
28
32
  - lib/local_development_gateway/database_router.rb
29
33
  - lib/local_development_gateway/database_router/docker_api.rb
30
34
  - lib/local_development_gateway/database_router/docker_routes.rb