local-development-gateway 0.2.4 → 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 +73 -33
- data/docs/architecture/local-tcp-routing.md +6 -8
- 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
|
|
|
@@ -150,18 +149,60 @@ connects locally.
|
|
|
150
149
|
|
|
151
150
|
### Private database alias length
|
|
152
151
|
|
|
153
|
-
The complete
|
|
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
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
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.
|
|
159
165
|
|
|
160
|
-
|
|
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.
|
|
161
167
|
|
|
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
|
|
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.
|
|
163
169
|
|
|
164
|
-
|
|
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.
|
|
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,
|
|
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: "${
|
|
187
|
-
PGHOST: "${
|
|
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: "${
|
|
191
|
-
PGHOST: "${
|
|
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: "${
|
|
195
|
-
PGHOST: "${
|
|
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
|
-
- "${
|
|
237
|
+
- "${DB_HOST:?derive with database_alias}"
|
|
201
238
|
db_trav_com:
|
|
202
239
|
networks:
|
|
203
240
|
default:
|
|
204
241
|
aliases:
|
|
205
|
-
- "${
|
|
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
|
|
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`.
|
|
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,11 @@ 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.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
|
+
|
|
453
493
|
## Release 0.2.4
|
|
454
494
|
|
|
455
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.
|
|
@@ -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,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
|
|
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
|
-
-
|
|
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
|
|
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
|
-
-
|
|
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
|
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
|