@solid-stack/builder 2.2.0 → 3.1.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.
- package/README.md +41 -591
- package/dist/bin.js +1783 -1946
- package/dist/bin.js.map +1 -1
- package/dist/commands/mesh/command.d.ts.map +1 -1
- package/dist/commands/mesh/commands/down/handler.d.ts.map +1 -1
- package/dist/commands/mesh/commands/up/command.d.ts.map +1 -1
- package/dist/commands/mesh/commands/up/handler.d.ts.map +1 -1
- package/dist/commands/prune/command.d.ts.map +1 -1
- package/dist/commands/prune/handler.d.ts +3 -1
- package/dist/commands/prune/handler.d.ts.map +1 -1
- package/dist/commands/service/command.d.ts.map +1 -1
- package/dist/commands/service/commands/down/handler.d.ts.map +1 -1
- package/dist/commands/service/commands/up/command.d.ts.map +1 -1
- package/dist/commands/service/commands/up/handler.d.ts.map +1 -1
- package/dist/core/buildSchema.d.ts +223 -952
- package/dist/core/buildSchema.d.ts.map +1 -1
- package/dist/core/checkers/checkDockerfileContract.d.ts +1 -0
- package/dist/core/checkers/checkDockerfileContract.d.ts.map +1 -1
- package/dist/core/checkers/checkInfra.d.ts +7 -1
- package/dist/core/checkers/checkInfra.d.ts.map +1 -1
- package/dist/core/checkers/getDeclaredYamlFiles.d.ts +1 -1
- package/dist/core/checkers/getDeclaredYamlFiles.d.ts.map +1 -1
- package/dist/core/compileApplicationEnv.d.ts +7 -2
- package/dist/core/compileApplicationEnv.d.ts.map +1 -1
- package/dist/core/compileEnvironment.d.ts +1 -0
- package/dist/core/compileEnvironment.d.ts.map +1 -1
- package/dist/core/composeCleanup.d.ts.map +1 -1
- package/dist/core/composition/compileGraphComposition.d.ts +16 -0
- package/dist/core/composition/compileGraphComposition.d.ts.map +1 -0
- package/dist/core/composition/compileServiceComposition.d.ts +2 -13
- package/dist/core/composition/compileServiceComposition.d.ts.map +1 -1
- package/dist/core/composition/compileTester.d.ts +24 -0
- package/dist/core/composition/compileTester.d.ts.map +1 -0
- package/dist/core/composition/composeDependsOn.d.ts +8 -4
- package/dist/core/composition/composeDependsOn.d.ts.map +1 -1
- package/dist/core/composition/composeEnvironment.d.ts +1 -0
- package/dist/core/composition/composeEnvironment.d.ts.map +1 -1
- package/dist/core/composition/composeHealthcheck.d.ts.map +1 -1
- package/dist/core/composition/dotenv.d.ts +3 -0
- package/dist/core/composition/dotenv.d.ts.map +1 -0
- package/dist/core/composition/generatedNames.d.ts.map +1 -1
- package/dist/core/composition/inspectRequiredHealth.d.ts +11 -0
- package/dist/core/composition/inspectRequiredHealth.d.ts.map +1 -0
- package/dist/core/composition/mergeMainOverride.d.ts +3 -0
- package/dist/core/composition/mergeMainOverride.d.ts.map +1 -0
- package/dist/core/composition/types.d.ts +21 -39
- package/dist/core/composition/types.d.ts.map +1 -1
- package/dist/core/composition/validateMaterializedComposeBuildInputs.d.ts.map +1 -1
- package/dist/core/composition/validateMaterializedComposeFiles.d.ts.map +1 -1
- package/dist/core/composition/validateOverrideCompose.d.ts +4 -4
- package/dist/core/composition/validateOverrideCompose.d.ts.map +1 -1
- package/dist/core/composition/validateServiceCompose.d.ts +12 -0
- package/dist/core/composition/validateServiceCompose.d.ts.map +1 -0
- package/dist/core/config/constants.d.ts +2 -4
- package/dist/core/config/constants.d.ts.map +1 -1
- package/dist/core/config/endpointProperties.d.ts +2 -2
- package/dist/core/config/endpointProperties.d.ts.map +1 -1
- package/dist/core/config/executionProfile.d.ts +11 -0
- package/dist/core/config/executionProfile.d.ts.map +1 -0
- package/dist/core/config/hostPorts.d.ts +7 -1
- package/dist/core/config/hostPorts.d.ts.map +1 -1
- package/dist/core/config/publication.d.ts +11 -0
- package/dist/core/config/publication.d.ts.map +1 -0
- package/dist/core/config/references.d.ts +15 -15
- package/dist/core/config/references.d.ts.map +1 -1
- package/dist/core/config/resolveBuildStage.d.ts.map +1 -1
- package/dist/core/config/resolveMeshStage.d.ts +1 -1
- package/dist/core/config/resolveMeshStage.d.ts.map +1 -1
- package/dist/core/config/serviceGraph.d.ts +10 -0
- package/dist/core/config/serviceGraph.d.ts.map +1 -0
- package/dist/core/config/stageMerge.d.ts +2 -3
- package/dist/core/config/stageMerge.d.ts.map +1 -1
- package/dist/core/config/types.d.ts +107 -27
- package/dist/core/config/types.d.ts.map +1 -1
- package/dist/core/mesh/applyMeshExtends.d.ts +3 -0
- package/dist/core/mesh/applyMeshExtends.d.ts.map +1 -0
- package/dist/core/mesh/checkers/checkMesh.d.ts +2 -0
- package/dist/core/mesh/checkers/checkMesh.d.ts.map +1 -1
- package/dist/core/mesh/checkers/checkMeshServices.d.ts +2 -1
- package/dist/core/mesh/checkers/checkMeshServices.d.ts.map +1 -1
- package/dist/core/mesh/checkers/checkMeshTester.d.ts +1 -3
- package/dist/core/mesh/checkers/checkMeshTester.d.ts.map +1 -1
- package/dist/core/mesh/compileMeshComposition.d.ts +6 -0
- package/dist/core/mesh/compileMeshComposition.d.ts.map +1 -0
- package/dist/core/mesh/compileMeshEnvironment.d.ts +3 -2
- package/dist/core/mesh/compileMeshEnvironment.d.ts.map +1 -1
- package/dist/core/mesh/loadMeshSources.d.ts +4 -0
- package/dist/core/mesh/loadMeshSources.d.ts.map +1 -0
- package/dist/core/mesh/meshSchema.d.ts +41 -225
- package/dist/core/mesh/meshSchema.d.ts.map +1 -1
- package/dist/core/mesh/runners/runMeshDev.d.ts +1 -1
- package/dist/core/mesh/runners/runMeshDev.d.ts.map +1 -1
- package/dist/core/mesh/runners/runMeshProd.d.ts +1 -1
- package/dist/core/mesh/runners/runMeshProd.d.ts.map +1 -1
- package/dist/core/mesh/runners/runMeshServiceTests.d.ts +2 -1
- package/dist/core/mesh/runners/runMeshServiceTests.d.ts.map +1 -1
- package/dist/core/mesh/runners/runMeshTest.d.ts +7 -1
- package/dist/core/mesh/runners/runMeshTest.d.ts.map +1 -1
- package/dist/core/mesh/runners/runMeshTestE2e.d.ts +2 -1
- package/dist/core/mesh/runners/runMeshTestE2e.d.ts.map +1 -1
- package/dist/core/mesh/types.d.ts +18 -24
- package/dist/core/mesh/types.d.ts.map +1 -1
- package/dist/core/runCompose.d.ts +4 -0
- package/dist/core/runCompose.d.ts.map +1 -1
- package/dist/core/runners/runDev.d.ts.map +1 -1
- package/dist/core/runners/runFiniteTester.d.ts +12 -2
- package/dist/core/runners/runFiniteTester.d.ts.map +1 -1
- package/dist/core/runners/runLongLived.d.ts +15 -0
- package/dist/core/runners/runLongLived.d.ts.map +1 -0
- package/dist/core/runners/runProd.d.ts.map +1 -1
- package/dist/core/runners/runTest.d.ts +7 -1
- package/dist/core/runners/runTest.d.ts.map +1 -1
- package/dist/core/runners/runTestE2e.d.ts +9 -1
- package/dist/core/runners/runTestE2e.d.ts.map +1 -1
- package/dist/core/runners/runTestUnit.d.ts +9 -1
- package/dist/core/runners/runTestUnit.d.ts.map +1 -1
- package/dist/index.js +1786 -1947
- package/dist/index.js.map +1 -1
- package/dist/templates/docker/docker-compose.base.yml +1 -1
- package/dist/templates/docker/docker-compose.dev.yml +1 -4
- package/dist/templates/docker/docker-compose.e2e.yml +1 -6
- package/dist/templates/docker/docker-compose.prod.yml +1 -1
- package/dist/templates/docker/docker-compose.test.yml +1 -1
- package/dist/templates/policy/dockerfile/dockerfile.rego +3 -6
- package/dist/types/index.d.ts +54 -32
- package/dist/types/index.d.ts.map +1 -1
- package/dist/utils/runState.d.ts +9 -1
- package/dist/utils/runState.d.ts.map +1 -1
- package/package.json +11 -6
- package/schemas/build-schema.json +889 -498
- package/schemas/mesh-schema.json +971 -384
- package/templates/docker/docker-compose.base.yml +1 -1
- package/templates/docker/docker-compose.dev.yml +1 -4
- package/templates/docker/docker-compose.e2e.yml +1 -6
- package/templates/docker/docker-compose.prod.yml +1 -1
- package/templates/docker/docker-compose.test.yml +1 -1
- package/templates/policy/dockerfile/dockerfile.rego +3 -6
- package/dist/core/composition/dependencyLifecycle.d.ts +0 -4
- package/dist/core/composition/dependencyLifecycle.d.ts.map +0 -1
- package/dist/core/composition/mergeAppOverride.d.ts +0 -3
- package/dist/core/composition/mergeAppOverride.d.ts.map +0 -1
- package/dist/core/composition/selectAppEnvironmentEntries.d.ts +0 -3
- package/dist/core/composition/selectAppEnvironmentEntries.d.ts.map +0 -1
- package/dist/core/composition/serviceEndpoints.d.ts +0 -5
- package/dist/core/composition/serviceEndpoints.d.ts.map +0 -1
- package/dist/core/composition/validateDependencyCompose.d.ts +0 -8
- package/dist/core/composition/validateDependencyCompose.d.ts.map +0 -1
- package/dist/core/mesh/v2/compileMeshComposition.d.ts +0 -6
- package/dist/core/mesh/v2/compileMeshComposition.d.ts.map +0 -1
- package/dist/core/mesh/v2/compileMeshTester.d.ts +0 -15
- package/dist/core/mesh/v2/compileMeshTester.d.ts.map +0 -1
- package/dist/core/mesh/v2/lifecycle.d.ts +0 -10
- package/dist/core/mesh/v2/lifecycle.d.ts.map +0 -1
- package/dist/core/mesh/v2/loadMeshServices.d.ts +0 -5
- package/dist/core/mesh/v2/loadMeshServices.d.ts.map +0 -1
- package/dist/core/mesh/v2/meshReferences.d.ts +0 -17
- package/dist/core/mesh/v2/meshReferences.d.ts.map +0 -1
- package/dist/core/mesh/v2/publication.d.ts +0 -3
- package/dist/core/mesh/v2/publication.d.ts.map +0 -1
- package/dist/core/mesh/v2/resolveMeshAppEnvironment.d.ts +0 -4
- package/dist/core/mesh/v2/resolveMeshAppEnvironment.d.ts.map +0 -1
- package/dist/core/mesh/v2/substitution.d.ts +0 -5
- package/dist/core/mesh/v2/substitution.d.ts.map +0 -1
- package/dist/core/mesh/v2/types.d.ts +0 -40
- package/dist/core/mesh/v2/types.d.ts.map +0 -1
package/README.md
CHANGED
|
@@ -1,627 +1,77 @@
|
|
|
1
|
-
# Solid Stack Builder
|
|
1
|
+
# Solid Stack Builder V3
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Builder 3.1.0 compiles a service's `build.json` or a system's `mesh.json` into Docker Compose. Services declare possible runtime modules; explicit **requisites** select which modules run and how they wait. Mesh sources stay independently runnable, with explicit `extends` rewrites when a real service replaces a local mock. Main services can declare stage-aware Docker `buildArgs`.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
The source package declares version 3.1.0. This checkout does not imply that version has been published to a package registry. For a local checkout, run `pnpm install`, `pnpm build`, and `node dist/bin.js --version`. The package exposes both `builder` and `solid-builder` when installed. Node.js 20 or newer and Docker Engine with Compose are required for runtime commands.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
[Builder V3 documentation](docs/README.md)
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
- **Named endpoints instead of hardcoded URLs and ports.**
|
|
11
|
-
- **Local dependency implementations** backed by Docker Compose.
|
|
12
|
-
- **Dependency substitution in a mesh** so a local mock can be replaced by a real top-level service.
|
|
13
|
-
- **Private-by-default mesh networking** with explicit host publication.
|
|
14
|
-
- **Fixed or automatic host ports** through `publicPort`.
|
|
15
|
-
- **Health-gated startup ordering** for applications and dependencies.
|
|
16
|
-
- **Stage overlays** for `dev`, `prod`, `test`, and `e2e`.
|
|
17
|
-
- **Service-level and global E2E testing** with endpoint references instead of guessed addresses.
|
|
18
|
-
- **Preflight validation** for Dockerfiles, Builder configuration, dependency Compose files, and mesh contracts.
|
|
9
|
+
[Upgrade from Builder 2.2.0](docs/migration/v2.2-to-v3.0.md)
|
|
19
10
|
|
|
20
|
-
|
|
11
|
+
[Upgrade from Builder 3.0.0](docs/migration/v3.0-to-v3.1.md)
|
|
21
12
|
|
|
22
|
-
|
|
13
|
+
## Tests
|
|
23
14
|
|
|
24
|
-
-
|
|
25
|
-
- Docker Engine with a reachable daemon;
|
|
26
|
-
- Docker Compose **2.24.0 or newer**.
|
|
15
|
+
Run `pnpm test` for the complete V3 verification suite. It runs non-Docker tests, typechecking, build and API checks first, then the three Docker acceptance tests. Docker tests require a prepared local fixture image; run `pnpm test:v3:prepare` once when the fixture is missing or stale. For a quick run without Docker, use `pnpm test:v3:fast`.
|
|
27
16
|
|
|
28
|
-
|
|
17
|
+
## A service
|
|
29
18
|
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
Install the package globally:
|
|
33
|
-
|
|
34
|
-
```bash
|
|
35
|
-
pnpm add -g @solid-stack/builder
|
|
36
|
-
```
|
|
37
|
-
|
|
38
|
-
or:
|
|
39
|
-
|
|
40
|
-
```bash
|
|
41
|
-
npm install -g @solid-stack/builder
|
|
42
|
-
```
|
|
43
|
-
|
|
44
|
-
The package exposes both `builder` and `solid-builder`. The documentation uses `builder`.
|
|
45
|
-
|
|
46
|
-
Verify the installation:
|
|
47
|
-
|
|
48
|
-
```bash
|
|
49
|
-
builder --version
|
|
50
|
-
builder --help
|
|
51
|
-
```
|
|
52
|
-
|
|
53
|
-
## Core mental model
|
|
54
|
-
|
|
55
|
-
Builder has two configuration files with separate responsibilities:
|
|
56
|
-
|
|
57
|
-
| File | Responsibility |
|
|
58
|
-
|---|---|
|
|
59
|
-
| `build.json` | Describes one independently runnable service: its app endpoints, runtime environment, local dependency implementations, tester environment, and stage-specific changes. |
|
|
60
|
-
| `mesh.json` | Describes how independently runnable services are composed: service paths, dependency substitutions, mesh-owned environment values, startup dependencies, host publication, and the global E2E tester. |
|
|
61
|
-
|
|
62
|
-
A `build.json` never chooses which top-level mesh service replaces one of its dependencies. A `mesh.json` never redefines an application's endpoint ports. This separation keeps each service runnable on its own while allowing larger systems to compose it differently.
|
|
63
|
-
|
|
64
|
-
---
|
|
65
|
-
|
|
66
|
-
# Quick start: one service
|
|
67
|
-
|
|
68
|
-
A Builder service directory normally contains at least:
|
|
69
|
-
|
|
70
|
-
```text
|
|
71
|
-
my-api/
|
|
72
|
-
├── build.json
|
|
73
|
-
├── Dockerfile
|
|
74
|
-
└── ...application files
|
|
75
|
-
```
|
|
76
|
-
|
|
77
|
-
## 1. Define the service
|
|
78
|
-
|
|
79
|
-
Create `build.json`:
|
|
19
|
+
`build.json` (complete minimal configuration):
|
|
80
20
|
|
|
81
21
|
```json
|
|
82
22
|
{
|
|
83
23
|
"name": "my-api",
|
|
84
|
-
"
|
|
85
|
-
"
|
|
86
|
-
"http": {
|
|
87
|
-
"port": 3000,
|
|
88
|
-
"publicPort": "AUTO",
|
|
89
|
-
"primary": true,
|
|
90
|
-
"scheme": "http"
|
|
91
|
-
}
|
|
92
|
-
}
|
|
93
|
-
}
|
|
94
|
-
}
|
|
95
|
-
```
|
|
96
|
-
|
|
97
|
-
The endpoint means:
|
|
98
|
-
|
|
99
|
-
- the app listens on container port `3000`;
|
|
100
|
-
- it may be reached from the host because `publicPort` is declared;
|
|
101
|
-
- Builder chooses an available host port because the value is `"AUTO"`;
|
|
102
|
-
- the endpoint is the app's primary endpoint, so Builder injects `PORT=3000`;
|
|
103
|
-
- URL references can be constructed because `scheme` is `http`.
|
|
104
|
-
|
|
105
|
-
## 2. Provide the Dockerfile targets
|
|
106
|
-
|
|
107
|
-
A Builder application Dockerfile must expose the expected stage contract:
|
|
108
|
-
|
|
109
|
-
```text
|
|
110
|
-
dev
|
|
111
|
-
test
|
|
112
|
-
test-e2e
|
|
113
|
-
prod
|
|
114
|
-
```
|
|
115
|
-
|
|
116
|
-
`dev` and `prod` must provide a valid Docker healthcheck. Network applications should use the Builder-provided `PORT` rather than assuming a fixed application port.
|
|
117
|
-
|
|
118
|
-
## 3. Validate the project
|
|
119
|
-
|
|
120
|
-
```bash
|
|
121
|
-
builder check
|
|
122
|
-
```
|
|
123
|
-
|
|
124
|
-
From another directory:
|
|
125
|
-
|
|
126
|
-
```bash
|
|
127
|
-
builder check -C ./services/my-api
|
|
128
|
-
```
|
|
129
|
-
|
|
130
|
-
## 4. Run development
|
|
131
|
-
|
|
132
|
-
```bash
|
|
133
|
-
builder service up dev
|
|
134
|
-
```
|
|
135
|
-
|
|
136
|
-
Development is isolated by default: local dependency implementations are not started.
|
|
137
|
-
|
|
138
|
-
To run development with all endpoint-bearing local dependencies:
|
|
139
|
-
|
|
140
|
-
```bash
|
|
141
|
-
builder service up dev --full
|
|
142
|
-
```
|
|
143
|
-
|
|
144
|
-
Stop it with:
|
|
145
|
-
|
|
146
|
-
```bash
|
|
147
|
-
builder service down dev
|
|
148
|
-
```
|
|
149
|
-
|
|
150
|
-
---
|
|
151
|
-
|
|
152
|
-
# Add a local dependency
|
|
153
|
-
|
|
154
|
-
A dependency is a **logical dependency** backed by one Compose implementation and zero or more named endpoints.
|
|
155
|
-
|
|
156
|
-
```json
|
|
157
|
-
{
|
|
158
|
-
"name": "my-api",
|
|
159
|
-
"app": {
|
|
160
|
-
"env": {
|
|
161
|
-
"DATABASE_HOST": "${dependencies.database.endpoints.tcp.network_host}",
|
|
162
|
-
"DATABASE_PORT": "${dependencies.database.endpoints.tcp.network_port}"
|
|
163
|
-
},
|
|
164
|
-
"endpoints": {
|
|
165
|
-
"http": {
|
|
166
|
-
"port": 3000,
|
|
167
|
-
"publicPort": "AUTO",
|
|
168
|
-
"primary": true,
|
|
169
|
-
"scheme": "http"
|
|
170
|
-
}
|
|
171
|
-
}
|
|
172
|
-
},
|
|
173
|
-
"dependencies": {
|
|
174
|
-
"database": {
|
|
175
|
-
"compose": ".docker/dependencies/database.compose.yml",
|
|
24
|
+
"services": {
|
|
25
|
+
"main": {
|
|
176
26
|
"endpoints": {
|
|
177
|
-
"
|
|
178
|
-
"service": "postgres",
|
|
179
|
-
"port": 5432,
|
|
180
|
-
"primary": true
|
|
181
|
-
}
|
|
27
|
+
"http": { "port": 3000, "publicPort": "AUTO", "primary": true, "scheme": "http" }
|
|
182
28
|
}
|
|
183
|
-
}
|
|
184
|
-
}
|
|
185
|
-
}
|
|
186
|
-
```
|
|
187
|
-
|
|
188
|
-
The dependency endpoint's `service` must exactly name the owning service in the dependency Compose file. Builder does not infer the first service or guess which container owns the endpoint.
|
|
189
|
-
|
|
190
|
-
If a dependency has no effective endpoints, it is inert and is not materialized at runtime.
|
|
191
|
-
|
|
192
|
-
Dependency Compose files must keep endpoint-owning services healthcheckable. Builder uses those healthchecks to decide when a dependency is ready.
|
|
193
|
-
|
|
194
|
-
---
|
|
195
|
-
|
|
196
|
-
# Endpoint references
|
|
197
|
-
|
|
198
|
-
Builder-managed JSON environment values can refer to endpoint properties instead of hardcoding generated addresses.
|
|
199
|
-
|
|
200
|
-
Inside `build.json`:
|
|
201
|
-
|
|
202
|
-
```text
|
|
203
|
-
${app.endpoints.<endpoint>.<property>}
|
|
204
|
-
${dependencies.<dependency>.endpoints.<endpoint>.<property>}
|
|
205
|
-
```
|
|
206
|
-
|
|
207
|
-
Inside `mesh.json`:
|
|
208
|
-
|
|
209
|
-
```text
|
|
210
|
-
${<service>.app.endpoints.<endpoint>.<property>}
|
|
211
|
-
${<service>.dependencies.<dependency>.endpoints.<endpoint>.<property>}
|
|
212
|
-
```
|
|
213
|
-
|
|
214
|
-
Available properties:
|
|
215
|
-
|
|
216
|
-
| Property | Meaning | Needs `scheme` | Needs effective host publication |
|
|
217
|
-
|---|---|---:|---:|
|
|
218
|
-
| `network_host` | Internal DNS host | No | No |
|
|
219
|
-
| `network_port` | Internal container port | No | No |
|
|
220
|
-
| `network_address` | `host:port` on the internal network | No | No |
|
|
221
|
-
| `network_url` | `scheme://host:port` on the internal network | Yes | No |
|
|
222
|
-
| `public_host` | Host-facing address, currently `127.0.0.1` | No | Yes |
|
|
223
|
-
| `public_port` | Resolved host port | No | Yes |
|
|
224
|
-
| `public_address` | `host:port` from the host | No | Yes |
|
|
225
|
-
| `public_url` | `scheme://host:port` from the host | Yes | Yes |
|
|
226
|
-
|
|
227
|
-
References can be embedded inside larger strings:
|
|
228
|
-
|
|
229
|
-
```json
|
|
230
|
-
{
|
|
231
|
-
"API_URL": "${dependencies.backend.endpoints.http.network_url}/v1"
|
|
232
|
-
}
|
|
233
|
-
```
|
|
234
|
-
|
|
235
|
-
Use `$$` when a literal dollar escape is required in Builder-managed environment strings.
|
|
236
|
-
|
|
237
|
-
---
|
|
238
|
-
|
|
239
|
-
# Service stages
|
|
240
|
-
|
|
241
|
-
Builder has four configuration overlays but five service commands for execution/testing:
|
|
242
|
-
|
|
243
|
-
| Command | Config overlay | Dockerfile target | Local dependencies | Purpose |
|
|
244
|
-
|---|---|---|---|---|
|
|
245
|
-
| `builder service up dev` | `dev` | `dev` | Isolated | Normal development |
|
|
246
|
-
| `builder service up dev --full` | `dev` | `dev` | Integrated | Development with local dependencies |
|
|
247
|
-
| `builder service up prod` | `prod` | `prod` | Integrated | Production-style runtime |
|
|
248
|
-
| `builder service up test-unit` | `test` | `test` | Isolated | Unit/integration test runner |
|
|
249
|
-
| `builder service up test-e2e` | `base -> prod -> e2e` | app=`prod`, tester=`test-e2e` | Integrated | Service-level E2E |
|
|
250
|
-
| `builder service up test` | `test` then `e2e` | test, then prod/test-e2e | As above | Unit tests first, then E2E |
|
|
251
|
-
|
|
252
|
-
E2E uses production-shaped structured configuration: `base -> prod -> e2e`. The app runs Docker target `prod` with `EXEC_MODE=prod` and `INFRA_MODE=integrated`, while its dotenv source remains `.env.e2e`. `.env.prod` is not merged into `.env.e2e`.
|
|
253
|
-
|
|
254
|
-
---
|
|
255
|
-
|
|
256
|
-
# Quick start: a service mesh
|
|
257
|
-
|
|
258
|
-
A mesh composes service projects that can already run independently.
|
|
259
|
-
|
|
260
|
-
```text
|
|
261
|
-
system/
|
|
262
|
-
├── mesh.json
|
|
263
|
-
└── services/
|
|
264
|
-
├── frontend/
|
|
265
|
-
│ ├── build.json
|
|
266
|
-
│ └── Dockerfile
|
|
267
|
-
└── backend/
|
|
268
|
-
├── build.json
|
|
269
|
-
└── Dockerfile
|
|
270
|
-
```
|
|
271
|
-
|
|
272
|
-
Create `mesh.json`:
|
|
273
|
-
|
|
274
|
-
```json
|
|
275
|
-
{
|
|
276
|
-
"name": "system",
|
|
277
|
-
"services": {
|
|
278
|
-
"backend": {
|
|
279
|
-
"path": "./services/backend"
|
|
280
29
|
},
|
|
281
|
-
"
|
|
282
|
-
"path": "./services/frontend",
|
|
283
|
-
"dependencies": {
|
|
284
|
-
"backend": "backend"
|
|
285
|
-
},
|
|
286
|
-
"publish": [
|
|
287
|
-
"app.endpoints.http"
|
|
288
|
-
]
|
|
289
|
-
}
|
|
290
|
-
}
|
|
291
|
-
}
|
|
292
|
-
```
|
|
293
|
-
|
|
294
|
-
The binding:
|
|
295
|
-
|
|
296
|
-
```json
|
|
297
|
-
"dependencies": {
|
|
298
|
-
"backend": "backend"
|
|
299
|
-
}
|
|
300
|
-
```
|
|
301
|
-
|
|
302
|
-
means:
|
|
303
|
-
|
|
304
|
-
> for the `frontend` service's logical dependency named `backend`, use the top-level mesh service named `backend` instead of the frontend service's local dependency Compose implementation.
|
|
305
|
-
|
|
306
|
-
Substitution is atomic: the local implementation for that logical dependency is suppressed as a whole.
|
|
307
|
-
|
|
308
|
-
Run the mesh:
|
|
309
|
-
|
|
310
|
-
```bash
|
|
311
|
-
builder mesh check
|
|
312
|
-
builder mesh up dev
|
|
313
|
-
```
|
|
314
|
-
|
|
315
|
-
Stop it:
|
|
316
|
-
|
|
317
|
-
```bash
|
|
318
|
-
builder mesh down dev
|
|
319
|
-
```
|
|
320
|
-
|
|
321
|
-
---
|
|
322
|
-
|
|
323
|
-
# Mesh publication is explicit
|
|
324
|
-
|
|
325
|
-
Declaring `publicPort` in a service's `build.json` makes an endpoint *publishable*. It does not automatically make the endpoint host-visible inside a mesh.
|
|
326
|
-
|
|
327
|
-
The mesh must explicitly publish it:
|
|
328
|
-
|
|
329
|
-
```json
|
|
330
|
-
{
|
|
331
|
-
"services": {
|
|
332
|
-
"gateway": {
|
|
333
|
-
"path": "./services/gateway",
|
|
334
|
-
"publish": [
|
|
335
|
-
"app.endpoints.http"
|
|
336
|
-
]
|
|
337
|
-
}
|
|
30
|
+
"tester": { "compose": "./e2e/docker-compose.yml", "service": "runner" }
|
|
338
31
|
}
|
|
339
32
|
}
|
|
340
33
|
```
|
|
341
34
|
|
|
342
|
-
A
|
|
35
|
+
Provide a project `Dockerfile` with `dev`, `test`, and `prod` targets. The `dev` and `prod` main images need a usable healthcheck. The tester is a separate Compose implementation; its selected `runner` determines the E2E result. A minimal `e2e/docker-compose.yml` is:
|
|
343
36
|
|
|
344
|
-
```
|
|
345
|
-
|
|
346
|
-
|
|
37
|
+
```yaml
|
|
38
|
+
services:
|
|
39
|
+
runner:
|
|
40
|
+
image: alpine:3.20
|
|
41
|
+
command: ["sh", "-c", "exit 0"]
|
|
347
42
|
```
|
|
348
43
|
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
This makes it practical to keep databases, APIs, queues, and internal services private while publishing only the entry point that developers or external test clients need.
|
|
352
|
-
|
|
353
|
-
---
|
|
354
|
-
|
|
355
|
-
# Mesh stages
|
|
44
|
+
The [service quickstart](docs/getting-started/service-quickstart.md) gives a runnable tree. Run `builder check`, then `builder service up dev`; `builder service up dev --full` includes the effective requisite closure. `builder service up prod` uses the `prod` target and integrated graph. `builder service up test` runs isolated unit tests, cleans up, then runs service E2E with a production main and full graph.
|
|
356
45
|
|
|
357
|
-
|
|
|
358
|
-
|
|
359
|
-
| `
|
|
360
|
-
| `
|
|
361
|
-
| `
|
|
362
|
-
| `
|
|
46
|
+
| Workflow | Main target | Main execution mode | Infrastructure mode |
|
|
47
|
+
|---|---|---|---|
|
|
48
|
+
| `service up dev` | `dev` | `dev` | isolated |
|
|
49
|
+
| `service up dev --full` | `dev` | `dev` | integrated |
|
|
50
|
+
| `service up prod` | `prod` | `prod` | integrated |
|
|
51
|
+
| `service up test-unit` | `test` | `test` | isolated |
|
|
52
|
+
| `service up test-e2e` | `prod` | `prod` | integrated |
|
|
53
|
+
| `mesh up dev` / `prod` | `dev` / `prod` | same | integrated |
|
|
363
54
|
|
|
364
|
-
`
|
|
55
|
+
`test-unit` and `test-e2e` are standalone workflow names, not required Dockerfile targets.
|
|
365
56
|
|
|
366
|
-
|
|
57
|
+
## A mesh rewrite
|
|
367
58
|
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
A mesh can define a host-networked black-box tester:
|
|
59
|
+
A mesh has a required `name`, `services.tester`, and at least one source. To replace `frontend`'s local `backend` mock with a real `backend` source, remove the local edge and add the real one explicitly:
|
|
371
60
|
|
|
372
61
|
```json
|
|
373
|
-
{
|
|
374
|
-
"
|
|
375
|
-
|
|
376
|
-
"
|
|
377
|
-
|
|
378
|
-
"
|
|
379
|
-
}
|
|
380
|
-
},
|
|
381
|
-
"services": {
|
|
382
|
-
"gateway": {
|
|
383
|
-
"path": "./services/gateway",
|
|
384
|
-
"publish": [
|
|
385
|
-
"app.endpoints.http"
|
|
386
|
-
]
|
|
62
|
+
"frontend": {
|
|
63
|
+
"source": "./services/frontend",
|
|
64
|
+
"extends": {
|
|
65
|
+
"main": {
|
|
66
|
+
"requisites": { "source.backend": false, "backend": "dependency" },
|
|
67
|
+
"env": { "BACKEND_URL": "${backend.source.main.endpoints.http.network_url}" }
|
|
387
68
|
}
|
|
388
69
|
}
|
|
389
70
|
}
|
|
390
71
|
```
|
|
391
72
|
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
Use:
|
|
395
|
-
|
|
396
|
-
```bash
|
|
397
|
-
builder mesh up test-e2e
|
|
398
|
-
```
|
|
399
|
-
|
|
400
|
-
or the complete test pipeline:
|
|
401
|
-
|
|
402
|
-
```bash
|
|
403
|
-
builder mesh up test
|
|
404
|
-
```
|
|
405
|
-
|
|
406
|
-
---
|
|
407
|
-
|
|
408
|
-
# Command overview
|
|
409
|
-
|
|
410
|
-
## Global
|
|
411
|
-
|
|
412
|
-
```bash
|
|
413
|
-
builder --help
|
|
414
|
-
builder --version
|
|
415
|
-
builder --verbose <command>
|
|
416
|
-
```
|
|
417
|
-
|
|
418
|
-
`--verbose` includes stack traces for failures.
|
|
419
|
-
|
|
420
|
-
## Validate a service
|
|
421
|
-
|
|
422
|
-
```bash
|
|
423
|
-
builder check [-C <service-dir>]
|
|
424
|
-
```
|
|
425
|
-
|
|
426
|
-
## Run a service
|
|
427
|
-
|
|
428
|
-
```bash
|
|
429
|
-
builder service up [dev|prod|test|test-unit|test-e2e] [options]
|
|
430
|
-
```
|
|
431
|
-
|
|
432
|
-
Common options include:
|
|
433
|
-
|
|
434
|
-
```text
|
|
435
|
-
-C, --project-dir <dir>
|
|
436
|
-
-d, --detach
|
|
437
|
-
--debug
|
|
438
|
-
--dry-run
|
|
439
|
-
--skip-checks
|
|
440
|
-
--silence-warnings
|
|
441
|
-
--full
|
|
442
|
-
```
|
|
443
|
-
|
|
444
|
-
`--full` is meaningful for development and materializes declared local endpoint dependencies.
|
|
445
|
-
|
|
446
|
-
## Stop a service
|
|
447
|
-
|
|
448
|
-
```bash
|
|
449
|
-
builder service down [dev|prod|test|test-unit|test-e2e] [options]
|
|
450
|
-
```
|
|
451
|
-
|
|
452
|
-
Options:
|
|
453
|
-
|
|
454
|
-
```text
|
|
455
|
-
-C, --project-dir <dir>
|
|
456
|
-
-v, --volumes
|
|
457
|
-
--debug
|
|
458
|
-
```
|
|
459
|
-
|
|
460
|
-
## Export resolved application environment
|
|
461
|
-
|
|
462
|
-
```bash
|
|
463
|
-
builder service export env [dev|prod|test|e2e] [options]
|
|
464
|
-
```
|
|
465
|
-
|
|
466
|
-
Without a stage, Builder exports all four configuration stages.
|
|
467
|
-
|
|
468
|
-
Options:
|
|
469
|
-
|
|
470
|
-
```text
|
|
471
|
-
-C, --project-dir <dir>
|
|
472
|
-
--full
|
|
473
|
-
--silence-warnings
|
|
474
|
-
```
|
|
475
|
-
|
|
476
|
-
The default output names are `.env.dev`, `.env.prod`, `.env.test`, and `.env.e2e`.
|
|
477
|
-
|
|
478
|
-
## Validate a mesh
|
|
479
|
-
|
|
480
|
-
```bash
|
|
481
|
-
builder mesh check [options]
|
|
482
|
-
```
|
|
483
|
-
|
|
484
|
-
Options:
|
|
485
|
-
|
|
486
|
-
```text
|
|
487
|
-
-C, --project-dir <dir>
|
|
488
|
-
--require-tester
|
|
489
|
-
```
|
|
490
|
-
|
|
491
|
-
## Run a mesh
|
|
492
|
-
|
|
493
|
-
```bash
|
|
494
|
-
builder mesh up [dev|prod|test|test-e2e] [options]
|
|
495
|
-
```
|
|
496
|
-
|
|
497
|
-
Options:
|
|
498
|
-
|
|
499
|
-
```text
|
|
500
|
-
-C, --project-dir <dir>
|
|
501
|
-
-d, --detach
|
|
502
|
-
--debug
|
|
503
|
-
--dry-run
|
|
504
|
-
--skip-checks
|
|
505
|
-
--silence-warnings
|
|
506
|
-
```
|
|
507
|
-
|
|
508
|
-
## Stop a mesh
|
|
509
|
-
|
|
510
|
-
```bash
|
|
511
|
-
builder mesh down [dev|prod|test|test-e2e] [options]
|
|
512
|
-
```
|
|
513
|
-
|
|
514
|
-
Options:
|
|
515
|
-
|
|
516
|
-
```text
|
|
517
|
-
-C, --project-dir <dir>
|
|
518
|
-
-v, --volumes
|
|
519
|
-
--debug
|
|
520
|
-
```
|
|
521
|
-
|
|
522
|
-
## Clean unused Docker resources
|
|
523
|
-
|
|
524
|
-
```bash
|
|
525
|
-
builder prune
|
|
526
|
-
builder prune --volumes
|
|
527
|
-
```
|
|
528
|
-
|
|
529
|
-
`builder prune` removes stopped containers and unused networks. `--volumes` also prunes dangling volumes.
|
|
530
|
-
|
|
531
|
-
---
|
|
532
|
-
|
|
533
|
-
# Important usage rules
|
|
534
|
-
|
|
535
|
-
## One primary endpoint
|
|
536
|
-
|
|
537
|
-
If an app or dependency has a non-empty endpoint map, exactly one effective endpoint must have:
|
|
538
|
-
|
|
539
|
-
```json
|
|
540
|
-
"primary": true
|
|
541
|
-
```
|
|
542
|
-
|
|
543
|
-
For the app, that primary endpoint determines the Builder-owned `PORT` value.
|
|
544
|
-
|
|
545
|
-
## `publicPort` means publishable host access
|
|
546
|
-
|
|
547
|
-
Use a fixed port:
|
|
548
|
-
|
|
549
|
-
```json
|
|
550
|
-
"publicPort": 8080
|
|
551
|
-
```
|
|
552
|
-
|
|
553
|
-
or let Builder allocate one:
|
|
554
|
-
|
|
555
|
-
```json
|
|
556
|
-
"publicPort": "AUTO"
|
|
557
|
-
```
|
|
558
|
-
|
|
559
|
-
In standalone execution, eligible declared endpoints can be published directly. In a mesh, an endpoint is host-visible only when the effective mesh `publish` list selects it.
|
|
560
|
-
|
|
561
|
-
## Environment values are strings
|
|
562
|
-
|
|
563
|
-
Builder JSON environment maps are always:
|
|
564
|
-
|
|
565
|
-
```ts
|
|
566
|
-
Record<string, string>
|
|
567
|
-
```
|
|
568
|
-
|
|
569
|
-
Do not put numbers, booleans, arrays, objects, or `null` in Builder `env` maps.
|
|
570
|
-
|
|
571
|
-
## Environment references do not imply startup ordering
|
|
572
|
-
|
|
573
|
-
An environment value can establish *where* another service lives, but it does not mean Builder should wait for that service.
|
|
574
|
-
|
|
575
|
-
Use:
|
|
576
|
-
|
|
577
|
-
- dependency `dependsOn` for dependency-to-dependency readiness;
|
|
578
|
-
- mesh service `dependsOn` for explicit top-level service readiness;
|
|
579
|
-
- mesh dependency bindings for automatic consumer-to-provider readiness.
|
|
580
|
-
|
|
581
|
-
## Do not hardcode Builder-generated internal names
|
|
582
|
-
|
|
583
|
-
Dependency implementations are namespaced when Builder composes them. Always refer to logical endpoints through Builder references.
|
|
584
|
-
|
|
585
|
-
---
|
|
586
|
-
|
|
587
|
-
# Configuration reference
|
|
588
|
-
|
|
589
|
-
The current repository includes the normative V2 references:
|
|
590
|
-
|
|
591
|
-
- [`.docs/specs_v2/BUILD_JSON_DOCS.md`](.docs/specs_v2/BUILD_JSON_DOCS.md) — complete `build.json` field reference.
|
|
592
|
-
- [`.docs/specs_v2/MESH_JSON_DOCS.md`](.docs/specs_v2/MESH_JSON_DOCS.md) — complete `mesh.json` field reference.
|
|
593
|
-
- [`.docs/specs_v2/SPECS_V2.md`](.docs/specs_v2/SPECS_V2.md) — cross-file V2 behavior and invariants.
|
|
594
|
-
- [`schemas/build-schema.json`](schemas/build-schema.json) — generated `build.json` JSON Schema.
|
|
595
|
-
- [`schemas/mesh-schema.json`](schemas/mesh-schema.json) — generated `mesh.json` JSON Schema.
|
|
596
|
-
|
|
597
|
-
The long-form user documentation should be organized around workflows and usage rather than requiring users to read the specification end-to-end. See `docs_plan.md` for the proposed documentation structure.
|
|
598
|
-
|
|
599
|
-
---
|
|
600
|
-
|
|
601
|
-
# Repository development
|
|
602
|
-
|
|
603
|
-
When working on Builder itself:
|
|
604
|
-
|
|
605
|
-
```bash
|
|
606
|
-
pnpm install
|
|
607
|
-
pnpm typecheck
|
|
608
|
-
pnpm test
|
|
609
|
-
pnpm build
|
|
610
|
-
```
|
|
611
|
-
|
|
612
|
-
Useful verification commands:
|
|
613
|
-
|
|
614
|
-
```bash
|
|
615
|
-
pnpm test:conformance
|
|
616
|
-
pnpm test:docker
|
|
617
|
-
pnpm check
|
|
618
|
-
pnpm check:full
|
|
619
|
-
```
|
|
620
|
-
|
|
621
|
-
The default unit/conformance workflow is designed to run without requiring Docker for every test. Docker acceptance remains the final verification path for real Compose behavior.
|
|
622
|
-
|
|
623
|
-
---
|
|
73
|
+
That is an overlay fragment at `mesh.json.services.frontend`; see the [complete mesh example](docs/getting-started/mesh-quickstart.md). The reference alone does not add the edge. Mesh endpoints are private unless `publish` selects an already reachable endpoint with `publicPort`.
|
|
624
74
|
|
|
625
|
-
|
|
75
|
+
`builder mesh up test` tests each base source independently and sequentially, then starts a fresh global E2E composition. The public mesh `up` stages are `dev`, `prod`, and `test`.
|
|
626
76
|
|
|
627
|
-
See the
|
|
77
|
+
See the [configuration reference](docs/reference/build-json.md), [mesh reference](docs/reference/mesh-json.md), [CLI reference](docs/reference/cli.md), and [migration guide](docs/migration/v2.2-to-v3.0.md).
|