local-development-gateway 0.2.4 → 0.3.1

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: 769fae659862a5e04bbb1f4c1d572552afe3f777f4bbbd4ec007fa02860639c6
4
- data.tar.gz: e704decf7f614cb01a2a74ae1601fa6e925da9c243b3b4015ea9760e8ec45ae0
3
+ metadata.gz: 24db87232b01db912d8b0a561f1480cbd69a1d065fe06740060be81bc503a442
4
+ data.tar.gz: 7817485194e820a4b2ef05030d00cfd506e32a4bb6d495d5e850f049c41114ae
5
5
  SHA512:
6
- metadata.gz: 247d626136bee33123253a419d036812041b6e5df6094b14b262f5bc6be7ac629083aea1b717b64f8b29afce69b245b739fff47c0bcebc53c80b496351dbbb50
7
- data.tar.gz: 6954a6378a4aecf2d6c3d6eef08d8be001abfd2fc5c1758314b37b777d795ea6e7e7f16ec647eb128b0930353128f8c6f7be25539b1444d629f2dddd35e2ec7a
6
+ metadata.gz: a13b83fa299544b16575509c5f2e1680d2146794679ec694fe3d7b6c400cf6da88fddc69c6d7cc7932669fa3cf9cc01b7206c6da49d5f9b1fad648f80333dd89
7
+ data.tar.gz: 42ff41744c1c3576d699faa85cdab914b6374d178bc9569efa8fd329169b0576916387337e40905f0f6ed060c7c606825bdb7d275f13d62ca9fa83ff2d6e3348
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
 
@@ -150,18 +149,60 @@ connects locally.
150
149
 
151
150
  ### Private database alias length
152
151
 
153
- 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>`.
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:
154
153
 
155
- | Database service | Appended suffix | Maximum project-name length |
156
- | --- | --- | ---: |
157
- | `db` | `-db` | 60 |
158
- | `db_trav_com` | `-db_trav_com` | 51 |
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.
159
167
 
160
- 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.
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.
161
169
 
162
- 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.
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.
163
171
 
164
- 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.
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.
165
206
 
166
207
  ### Canonical development and test Compose pattern
167
208
 
@@ -172,44 +213,39 @@ existing configuration keys: `AZURE_SQL_HOST` is a SQL Server application
172
213
  example; `PGHOST` is the PostgreSQL/libpq equivalent. An application with a
173
214
  different PostgreSQL configuration key must set that key instead.
174
215
 
175
- For example, a wrapper-derived `COMPOSE_PROJECT_NAME=issue-123-example` gives
176
- private hosts `issue-123-example-db` and `issue-123-example-db_trav_com`.
177
- `GATEWAY_HOSTNAME=issue-123.example.localhost` separately identifies desktop
178
- routes. This requires no new Ruby API, generic database environment variable,
179
- 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.
180
217
 
181
218
  ```yaml
182
219
  # docker-compose.development.yml: also safe without the gateway overlay.
183
220
  services:
184
221
  api:
185
222
  environment:
186
- AZURE_SQL_HOST: "${COMPOSE_PROJECT_NAME}-db"
187
- 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}"
188
225
  jobs:
189
226
  environment:
190
- AZURE_SQL_HOST: "${COMPOSE_PROJECT_NAME}-db"
191
- 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}"
192
229
  test_api:
193
230
  environment:
194
- AZURE_SQL_HOST: "${COMPOSE_PROJECT_NAME}-db"
195
- 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}"
196
233
  db:
197
234
  networks:
198
235
  default:
199
236
  aliases:
200
- - "${COMPOSE_PROJECT_NAME}-db"
237
+ - "${DB_HOST:?derive with database_alias}"
201
238
  db_trav_com:
202
239
  networks:
203
240
  default:
204
241
  aliases:
205
- - "${COMPOSE_PROJECT_NAME}-db_trav_com"
242
+ - "${DB_TRAV_COM_HOST:?derive with database_alias}"
206
243
  ```
207
244
 
208
245
  The example's driver assignments are illustrative. In
209
246
  [Travel Authorization's overlay](https://github.com/icefoganalytics/travel-authorization/blob/main/docker-compose.development.gateway.yml),
210
247
  `db` is PostgreSQL and `db_trav_com` is SQL Server: its PostgreSQL host setting
211
- must use `${COMPOSE_PROJECT_NAME}-db`, and its SQL Server host setting must use
212
- `${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.
213
249
  Apply the rule separately to **every** database service, even when two services
214
250
  use the same driver. Preserve each context's existing credentials, internal
215
251
  port, and database name; tests must still select the test database rather than
@@ -322,10 +358,7 @@ retaining cancellation-aware PostgreSQL routing despite Traefik's STARTTLS suppo
322
358
 
323
359
  ### Downstream adoption checklist
324
360
 
325
- 1. Give each concurrent checkout a distinct Compose project name and desktop
326
- route hostname. Qualify every API/job/test database host with
327
- `${COMPOSE_PROJECT_NAME}-<database-service>` using its existing driver setting,
328
- within the [suffix-specific DNS budget](#private-database-alias-length).
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.
329
362
  2. Advertise each qualified alias only on its private `default` network;
330
363
  preserve it through mapping-form network merges in base-only and gateway modes.
331
364
  3. Remove fixed database publications from development/test stacks; retain
@@ -346,14 +379,15 @@ prevent an attached, malicious container from connecting to another database.
346
379
 
347
380
  ## Development checks
348
381
 
349
- Install the locked development tools with `bundle install`. Run the Ruby
350
- 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.
351
383
 
352
384
  ```sh
385
+ bundle exec rubocop --lint
353
386
  bundle exec ruby "$(bundle show syntax_tree)/exe/stree" check \
354
387
  Gemfile \
355
388
  Rakefile \
356
389
  lib/local_development_gateway.rb \
390
+ lib/local_development_gateway/database_alias.rb \
357
391
  lib/local_development_gateway/database_router.rb \
358
392
  lib/local_development_gateway/database_router/*.rb \
359
393
  lib/local_development_gateway/database_router/drivers/*.rb \
@@ -362,6 +396,7 @@ bundle exec ruby "$(bundle show syntax_tree)/exe/stree" check \
362
396
  lib/local_development_gateway/version.rb \
363
397
  bin/dev \
364
398
  bin/local-development-gateway \
399
+ examples/database-aliases/compose.rb \
365
400
  test/*.rb \
366
401
  test/database_router/*.rb \
367
402
  test/database_router/drivers/*.rb \
@@ -450,6 +485,16 @@ It mounts the Docker socket so it can discover labelled containers. A read-only
450
485
  | A project uses normal ports unexpectedly | Confirm the gateway container is running and has `local-gateway=true`. |
451
486
  | Authentication rejects the callback | Confirm the generated hostname matches the allowed wildcard callback pattern. |
452
487
 
488
+ ## Release 0.3.1
489
+
490
+ - Resolve the existing Ruby lint diagnostics without suppressions or reduced coverage. Clarify range and assertion boundaries, retain EOF handling through `IOError`, and use supported OpenSSL digest construction and socket-readiness APIs.
491
+ - Database routing, cancellation, lifecycle, and consumer alias contracts are unchanged; no shared gateway restart or consumer configuration change is required.
492
+
493
+ ## Release 0.3.0
494
+
495
+ - 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.
496
+ - 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.
497
+
453
498
  ## Release 0.2.4
454
499
 
455
500
  - 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.
@@ -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,7 +44,7 @@ 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 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.
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
48
 
49
49
  Gateway-mode development and test stacks publish no database host ports.
50
50
  Container consumers work with the base alone. Desktop access without the
@@ -59,14 +59,14 @@ the internal hostname correction.
59
59
 
60
60
  Requirements:
61
61
 
62
- - 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.
63
63
  - No consumer-side address allocator.
64
64
  - No per-worktree host-port selection.
65
65
  - No bind-address environment variable passed from application code.
66
66
  - No consumer startup or shutdown hook solely for gateway routing.
67
67
  - No consumer cleanup call.
68
68
  - No manually maintained DBeaver port per worktree.
69
- - The consumer supplies only declarative service identity and internal-port metadata.
69
+ - Desktop routing requires only declarative service identity and internal-port metadata.
70
70
 
71
71
  - No administrator or root installation.
72
72
  - No host `/etc/hosts`, DNS, resolver, systemd, or Windows-service changes.
@@ -279,13 +279,11 @@ instead of sharing a generic fixture layer.
279
279
  7. Stop A; A's route disappears while B remains available.
280
280
  8. Verify existing HTTP hostnames still use Traefik.
281
281
  9. Verify every host listener is loopback-only.
282
- 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.
283
283
 
284
284
  ## Non-Goals
285
285
 
286
- - Changing consumer application code, adding new development wrapper runtimes,
287
- or automatically mutating consumer networks. Existing Compose connection
288
- 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.
289
287
  - Requiring consumers to run DNS, a proxy, or host installation.
290
288
  - Assigning a different database port to each worktree.
291
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
@@ -48,14 +48,14 @@ module LocalDevelopmentGateway
48
48
  raise Error, "Invalid chunked Docker API response" unless line_end
49
49
 
50
50
  size = Integer(body.byteslice(0, line_end).split(";", 2).first, 16)
51
- body = body.byteslice(line_end + 2..)
51
+ body = body.byteslice((line_end + 2)..)
52
52
  break if size.zero?
53
53
  unless body.bytesize >= size + 2 && body.byteslice(size, 2) == "\r\n"
54
54
  raise Error, "Invalid chunked Docker API response"
55
55
  end
56
56
 
57
57
  decoded << body.byteslice(0, size)
58
- body = body.byteslice(size + 2..)
58
+ body = body.byteslice((size + 2)..)
59
59
  end
60
60
  decoded
61
61
  rescue ArgumentError, TypeError
@@ -28,7 +28,7 @@ module LocalDevelopmentGateway
28
28
  @certificate.add_extension(
29
29
  extensions.create_extension("extendedKeyUsage", "serverAuth")
30
30
  )
31
- @certificate.sign(@key, OpenSSL::Digest::SHA256.new)
31
+ @certificate.sign(@key, OpenSSL::Digest.new("SHA256"))
32
32
  end
33
33
 
34
34
  def context(&servername_callback)
@@ -80,7 +80,7 @@ module LocalDevelopmentGateway
80
80
  deadline: attempt_deadline
81
81
  )
82
82
  ]
83
- rescue Error, EOFError, IOError, SystemCallError
83
+ rescue Error, IOError, SystemCallError
84
84
  target&.close
85
85
  end
86
86
  raise Error, "No labelled SQL Server backends are reachable"
@@ -33,7 +33,7 @@ module LocalDevelopmentGateway
33
33
  break if @record_buffer.bytesize < length + 5
34
34
 
35
35
  @handshake << @record_buffer.byteslice(5, length)
36
- @record_buffer = @record_buffer.byteslice(length + 5..) || +""
36
+ @record_buffer = @record_buffer.byteslice((length + 5)..) || +""
37
37
  end
38
38
  end
39
39
 
@@ -38,7 +38,7 @@ module LocalDevelopmentGateway
38
38
  upstream =
39
39
  Thread.new do
40
40
  IO.copy_stream(client, target)
41
- rescue IOError, EOFError, OpenSSL::SSL::SSLError, SystemCallError
41
+ rescue IOError, OpenSSL::SSL::SSLError, SystemCallError
42
42
  nil
43
43
  ensure
44
44
  close_write(target)
@@ -50,7 +50,7 @@ module LocalDevelopmentGateway
50
50
  else
51
51
  IO.copy_stream(target, client)
52
52
  end
53
- rescue IOError, EOFError, OpenSSL::SSL::SSLError, SystemCallError
53
+ rescue IOError, OpenSSL::SSL::SSLError, SystemCallError
54
54
  nil
55
55
  ensure
56
56
  close_connection(client)
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module LocalDevelopmentGateway
4
- VERSION = "0.2.4"
4
+ VERSION = "0.3.1"
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.4
4
+ version: 0.3.1
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