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 +4 -4
- data/README.md +84 -24
- data/docs/architecture/local-tcp-routing.md +7 -7
- data/examples/database-aliases/compose.rb +41 -0
- data/examples/database-aliases/compose.yml +81 -0
- data/examples/database-aliases/gateway.yml +38 -0
- data/lib/local_development_gateway/database_alias.rb +27 -0
- data/lib/local_development_gateway/version.rb +1 -1
- data/lib/local_development_gateway.rb +1 -0
- metadata +6 -2
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: e7a28d928bf046ed735f00c3148307fb14c14d441b1cbc28e1d8d1014afc2855
|
|
4
|
+
data.tar.gz: fddfd6b3c2a1bae60dfb46e03531ee13988b0e697a69839566c006a3d92a709d
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
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.
|
|
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.
|
|
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 |
|
|
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,
|
|
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: "${
|
|
172
|
-
PGHOST: "${
|
|
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: "${
|
|
176
|
-
PGHOST: "${
|
|
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: "${
|
|
180
|
-
PGHOST: "${
|
|
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
|
-
- "${
|
|
237
|
+
- "${DB_HOST:?derive with database_alias}"
|
|
186
238
|
db_trav_com:
|
|
187
239
|
networks:
|
|
188
240
|
default:
|
|
189
241
|
aliases:
|
|
190
|
-
- "${
|
|
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
|
|
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`.
|
|
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 |
|
|
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
|
-
-
|
|
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
|
|
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
|
-
-
|
|
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
|
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.
|
|
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-
|
|
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
|