mirror of
https://github.com/dadosfera/maestro.git
synced 2026-10-15 06:19:08 +00:00
57 lines
2.9 KiB
Markdown
57 lines
2.9 KiB
Markdown
# maestro — development policy
|
|
|
|
Maestro is the NestJS BFF between the Angular frontend and the gRPC services
|
|
(pi-factory, in-factory) / platform-api. These rules come from code review and
|
|
apply to every change; the same rules live in pi-factory and in-factory.
|
|
|
|
## Layering
|
|
- Controllers are thin: decorators, body validation, one call into a service,
|
|
response shape. Orchestration (multi-step calls, rollbacks, platform-api or
|
|
gRPC round-trips) lives in a `*.service.ts`. Example:
|
|
`platform-api/pipeline-tables.service.ts`.
|
|
- One platform-api route per operation. If the platform already dispatches by
|
|
pipeline type (batch vs CDC), do not branch on the type here — call the
|
|
route that dispatches (e.g. `DELETE /pipeline/{id}/jobs` for table removal,
|
|
never `DELETE /jobs/{id}` from maestro).
|
|
|
|
## Types
|
|
- No `any` / `as any`. gRPC calls take the protospack request type exactly
|
|
(`AddCdcTableRequest`, `MarkTableDeletedRequest`, ...); DTOs and interfaces
|
|
are explicit classes/interfaces. Use `Record<string, T>` or `unknown` (with
|
|
narrowing) when a shape is genuinely open — never `any`.
|
|
- Protospack payloads are built in one mapper per entity (e.g.
|
|
`inputs/cdc-table.mapper.ts`), so a field that mirrors another
|
|
(`CdcTable.name` == `table_name`) is derived in exactly one place.
|
|
|
|
## Pipeline type
|
|
- Decide CDC vs batch with `src/utils/cdc.ts` (`isCdcPlugin`, `isCdcJob`,
|
|
`isCdcPipeline`), never with inline `plugin.endsWith('_cdc')`, `!!x`, or
|
|
the absence of some other data (e.g. "no run history ⇒ editable").
|
|
- The platform-api stamps `job.input.connector === 'cdc'` on CDC jobs; that
|
|
is the authoritative discriminator once a pipeline exists.
|
|
|
|
## Dependencies
|
|
- `@dadosfera/protospack-v2` is consumed from CodeArtifact, pinned to an exact
|
|
version (`npm i @dadosfera/protospack-v2@<version> --save-exact`). A `file:`
|
|
/ tarball reference is for local development only and must never be
|
|
committed. Note: `^3.40.0-beta.N` resolves to the stable `3.40.0` —
|
|
prereleases must be pinned exactly.
|
|
|
|
## Commits and releases
|
|
- Deploys are cut by semantic-release with the eslint preset: the commit
|
|
title MUST start with `FIX:` (patch), `UPDATE:` or `FEAT:` (minor). A
|
|
lowercase `feat(scope): ...` merges without producing a version, so the
|
|
code never reaches stg/prd.
|
|
- Pushing to `beta` deploys stg; `main` deploys prd.
|
|
|
|
## Tests
|
|
- Every service method with a rollback path has a spec covering the
|
|
happy path, the platform failure (rollback fires) and a rollback failure
|
|
(does not mask the original error). Run `npx jest <path>` for a folder,
|
|
`npx tsc --noEmit -p tsconfig.json` for types.
|
|
- Several gRPC client configs read `process.env` at import time, so the full
|
|
suite needs the service URLs set (any `0.0.0.0:<port>` value works):
|
|
`DUC_URL=0.0.0.0:50051 INFACTORY_URL=0.0.0.0:50052 PIFACTORY_URL=0.0.0.0:50053 npx jest`.
|
|
A `Cannot read properties of undefined (reading 'startsWith')` at import is
|
|
this, not a broken test.
|