init
This commit is contained in:
hashbro
@@ -0,0 +1,150 @@
|
||||
# Synchronous build API
|
||||
|
||||
`build_api` is the HTTP front of **coruna-lab-web**. It runs
|
||||
`frontend/tools/new_project.py` synchronously and publishes completed releases
|
||||
for a web server to serve directly from the local filesystem. Laravel lives in the
|
||||
sibling `coruna-lab` project and calls this API over the network.
|
||||
|
||||
## Storage layout
|
||||
|
||||
```text
|
||||
<artifact-root>/
|
||||
├── channel/<channel-id>/ # published web/, sync/, out/, manifest.json
|
||||
├── staging/<request-id>/ # private build workspaces
|
||||
└── locks/<channel-id>.lock # nonblocking advisory locks
|
||||
```
|
||||
|
||||
Staging and published releases are children of the same artifact root and are
|
||||
checked to be on the same filesystem. A successful build is renamed into
|
||||
`channel/<channel-id>` only after its required output and absence of symlinks
|
||||
have been verified. Builder failures remove staging and leave an existing
|
||||
release untouched.
|
||||
|
||||
Every release gets a `manifest.json` containing the normalized build input, its
|
||||
SHA-256 digest, request ID, build timestamp, and a digest of builder stdout.
|
||||
An identical input returns the existing manifest without running the builder.
|
||||
Different input for an existing channel returns `409`; `"force": true` replaces
|
||||
it after a new build succeeds.
|
||||
|
||||
## Configuration
|
||||
|
||||
The service reads:
|
||||
|
||||
- `BUILD_API_TOKEN` (required): exact Bearer token.
|
||||
- `BUILD_API_ARTIFACT_ROOT`: defaults to `artifacts/` in the repository.
|
||||
- `BUILD_API_PROJECT_SCRIPT`: defaults to `frontend/tools/new_project.py`.
|
||||
- `BUILD_API_PYTHON`: Python used to invoke the builder.
|
||||
- `BUILD_API_HOST` / `BUILD_API_PORT`: defaults to `127.0.0.1:8081`.
|
||||
- `BUILD_API_TIMEOUT`: synchronous build timeout in seconds, default `900`.
|
||||
|
||||
Install API dependencies, then run from the repository root:
|
||||
|
||||
```bash
|
||||
python3 -m venv .venv
|
||||
source .venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
|
||||
export BUILD_API_TOKEN="$(python3 -c 'import secrets; print(secrets.token_urlsafe(48))')"
|
||||
export BUILD_API_ARTIFACT_ROOT=/srv/coruna-artifacts
|
||||
python3 -m build_api
|
||||
```
|
||||
|
||||
The HTTP layer is **FastAPI** served by **Uvicorn**. Route contracts, status
|
||||
codes, and Bearer auth are unchanged for Laravel clients.
|
||||
|
||||
The builder contract is:
|
||||
|
||||
```text
|
||||
python new_project.py \
|
||||
--root <artifact-root>/staging/<request-id> \
|
||||
--channel-id <id> \
|
||||
--deployment-domains <domain> ... \
|
||||
--reporting-domains <domain> ...
|
||||
```
|
||||
|
||||
It must create a channel-scoped tree below `--root`:
|
||||
|
||||
```text
|
||||
<root>/
|
||||
├── web/support.html
|
||||
├── sync/daily.html
|
||||
├── out/
|
||||
└── manifest.json # includes channel_id, support_path, daily_path
|
||||
```
|
||||
|
||||
The API always passes `--force` because it pre-creates the staging directory.
|
||||
It never writes into the Laravel `public/` directory. Published static URLs are:
|
||||
|
||||
```text
|
||||
/channel/<id>/web/support.html
|
||||
/channel/<id>/sync/daily.html
|
||||
```
|
||||
|
||||
Run the API as a long-lived process (for example via a process manager in
|
||||
宝塔) and put a reverse proxy in front of `BUILD_API_HOST`/`BUILD_API_PORT`.
|
||||
Point the public static site document root at the artifact root so only
|
||||
`channel/<id>/web/` and `channel/<id>/sync/` are reachable; keep
|
||||
`staging/`, `locks/`, manifests, and `out/` private. The web server user
|
||||
needs read access to published releases; it should not have write access.
|
||||
|
||||
## API
|
||||
|
||||
Health is public:
|
||||
|
||||
```bash
|
||||
curl https://builds.example.com/health
|
||||
```
|
||||
|
||||
Build:
|
||||
|
||||
```bash
|
||||
curl -i -X POST \
|
||||
-H "Authorization: Bearer $BUILD_API_TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
https://builds.example.com/v1/channels/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/build \
|
||||
-d '{
|
||||
"deployment_domains": ["deploy.example"],
|
||||
"reporting_domains": ["report.example"]
|
||||
}'
|
||||
```
|
||||
|
||||
The first successful build returns `201`; the same normalized input returns
|
||||
`200`. A busy channel or conflicting existing release returns `409`, and an
|
||||
invalid channel, JSON body, domain, or field returns `422`.
|
||||
|
||||
Status and deletion:
|
||||
|
||||
```bash
|
||||
curl -H "Authorization: Bearer $BUILD_API_TOKEN" \
|
||||
https://builds.example.com/v1/channels/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
|
||||
|
||||
curl -i -X DELETE -H "Authorization: Bearer $BUILD_API_TOKEN" \
|
||||
https://builds.example.com/v1/channels/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
|
||||
```
|
||||
|
||||
Deletion returns `204` whether or not the release exists. It rejects symbolic
|
||||
links and takes the same per-channel lock as builds.
|
||||
|
||||
Public static URLs:
|
||||
|
||||
```text
|
||||
/channel/<channel-id>/web/support.html
|
||||
/channel/<channel-id>/sync/daily.html
|
||||
```
|
||||
|
||||
Only `web/` and `sync/` under each channel should be exposed; manifests,
|
||||
`out/`, staging, and locks stay private.
|
||||
|
||||
## Migration checklist
|
||||
|
||||
1. Deploy `build_api` + artifact root + reverse proxy / static site via your panel.
|
||||
2. Set Laravel `CORUNA_BUILD_SERVICE_*` and static-site domains.
|
||||
3. Create a new channel from Admin and verify support/daily URLs on the static host.
|
||||
4. Keep legacy `public/web` and `public/sync` read-only until old channels are rebuilt or retired.
|
||||
5. Device validation (ops): capture that the implant requests `/channel/<id>/sync/daily.html` then `/channel/<id>/sync/<wire>`.
|
||||
|
||||
## Tests
|
||||
|
||||
```bash
|
||||
python3 -m unittest -v tests.test_build_api
|
||||
```
|
||||
Reference in New Issue
Block a user