updates 33.1 84
This commit is contained in:
129
docs/data/en/station-shuntgen.md
Normal file
129
docs/data/en/station-shuntgen.md
Normal file
@@ -0,0 +1,129 @@
|
||||
# Shuntgen
|
||||
|
||||
Generates runnable [shunts](#artery-shunts) from the two things people actually
|
||||
have: a service contract, or a folder of spreadsheets.
|
||||
|
||||
Writing a shunt by hand means copying `artery/shunts/example/` and filling in
|
||||
`responses.json` entry by entry. That is fine for three endpoints and untenable
|
||||
for eighty — and it is the wrong work anyway, because the endpoints are already
|
||||
described in the spec somebody handed you.
|
||||
|
||||
```bash
|
||||
# a spec you were handed
|
||||
python -m station.tools.shuntgen from-openapi -s api.yaml -o artery/shunts/petstore
|
||||
|
||||
# sheets a client sent
|
||||
python -m station.tools.shuntgen from-tabular -s ./sheets -o artery/shunts/books
|
||||
|
||||
python -m station.tools.shuntgen list
|
||||
```
|
||||
|
||||
Run from `soleprint/`. Also in the browser at `/station/tools/shuntgen/`, where
|
||||
you can upload a spec, preview the routes it would serve, and generate.
|
||||
|
||||
## What comes out
|
||||
|
||||
```
|
||||
artery/shunts/<name>/
|
||||
main.py builds the app from the spec
|
||||
run.py uvicorn entry point (PORT, or depot/config.json)
|
||||
shunt_runtime.py vendored runtime — no soleprint import
|
||||
models.py pydantic, via modelgen
|
||||
datagen_<name>.py BaseDataGenerator subclass, via modelgen
|
||||
depot/spec.json routes, collections and schema
|
||||
depot/responses.json pinned overrides — yours, never overwritten
|
||||
depot/config.json delays, error rate, prefill — yours, never overwritten
|
||||
depot/data.json imported rows
|
||||
templates/index.html config UI
|
||||
README.md
|
||||
```
|
||||
|
||||
```bash
|
||||
cd artery/shunts/books && python run.py
|
||||
curl localhost:8098/customers
|
||||
```
|
||||
|
||||
The routes are built at startup from `spec.json` rather than written out as
|
||||
source. That keeps the generated code short enough to read, and puts the
|
||||
behaviour in one reviewable place: fixing `runtime.py` fixes every shunt, and
|
||||
regenerating is a copy.
|
||||
|
||||
## Where a response comes from
|
||||
|
||||
First hit wins:
|
||||
|
||||
1. `depot/responses.json` — a pinned override, keyed `"METHOD /path"`
|
||||
2. the store — rows imported from sheets, plus anything POSTed since
|
||||
3. the spec's `example`, if the source document carried one
|
||||
4. `datagen_<name>.py`, synthesising from the schema
|
||||
5. `{}`
|
||||
|
||||
The store is what makes it behave like a service rather than a random-value
|
||||
faucet: POST something and GET it back, ask for `/pets/7` and get the pet whose
|
||||
id is 7. Collections that arrived with no rows are prefilled with generated
|
||||
ones, so the first call answers with something.
|
||||
|
||||
## Two sources, one pipeline
|
||||
|
||||
Both inputs are [modelgen](#station-modelgen) extractors, so the same shapes
|
||||
also generate pydantic, TypeScript, prisma and a
|
||||
[graphgen](#station-graphgen) schema:
|
||||
|
||||
```bash
|
||||
python -m station.tools.modelgen from-openapi -s api.yaml -o out/ -t pydantic,typescript
|
||||
python -m station.tools.modelgen from-tabular -s ./sheets -o out/ -t schema,datagen
|
||||
```
|
||||
|
||||
| Source | Becomes | Routes |
|
||||
| --- | --- | --- |
|
||||
| OpenAPI 3.x / Swagger 2.0 | one model per schema; enums become real Enums, `$ref` becomes a relation | the operations the document declares |
|
||||
| `.csv` / `.tsv` / `.ods` | one model per file or sheet, types inferred per column | five CRUD routes per table |
|
||||
|
||||
Keys and relations are inferred by name and then **checked against the data**:
|
||||
an `id` column that is not unique is not treated as a key, and `customer_id` is
|
||||
only a foreign key if a `customers` sheet came with it.
|
||||
|
||||
ODS is read with `zipfile` and `ElementTree` — no odfpy, no pandas — which is
|
||||
what lets modelgen stay dependency-free and publishable on its own.
|
||||
|
||||
## Control endpoints
|
||||
|
||||
Every generated shunt serves these:
|
||||
|
||||
| Endpoint | Purpose |
|
||||
| --- | --- |
|
||||
| `GET /health` | liveness |
|
||||
| `GET /mock/spec` | the routes it was built from |
|
||||
| `GET /mock/stats` | call counts and row counts |
|
||||
| `POST /mock/reset` | restore the imported rows, clear counters |
|
||||
| `GET,POST /mock/config` | delays, error rate, `unknown_id`, page size |
|
||||
| `GET,POST /mock/responses` | pin an override; set a key to `null` to drop it |
|
||||
|
||||
```bash
|
||||
# make it slow and flaky, the way the real thing is
|
||||
curl -X POST localhost:8098/mock/config \
|
||||
-H 'content-type: application/json' \
|
||||
-d '{"enable_random_delays": true, "error_rate": 0.2}'
|
||||
|
||||
# make one call answer something specific
|
||||
curl -X POST localhost:8098/mock/responses \
|
||||
-H 'content-type: application/json' \
|
||||
-d '{"GET /customers/1": {"id": 1, "name": "PINNED"}}'
|
||||
```
|
||||
|
||||
`unknown_id` decides what an unknown key does: `generate` (the default) invents
|
||||
a record wearing the id that was asked for; `404` refuses it. Generate by
|
||||
default, because a client pointed at a fresh shunt should just work — flip it
|
||||
when the error path is what you are testing.
|
||||
|
||||
## Dependency containers
|
||||
|
||||
`--cabinet postgres,redis` writes a `cabinet.json` declaring what the shunt
|
||||
expects. `build.py` composes those services into the room's compose file, and on
|
||||
a cluster they install as rig addons of the same name. See
|
||||
[Cabinets](#station-cabinets).
|
||||
|
||||
## Regenerating
|
||||
|
||||
Everything is overwritten except `depot/responses.json` and `depot/config.json`.
|
||||
Those two are yours.
|
||||
Reference in New Issue
Block a user