@acropole/skills 1.0.0 → 1.2.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 +4 -2
- package/bin/install.js +4 -3
- package/package.json +2 -2
- package/skills/acropole/SKILL.md +9 -3
- package/skills/acropole/references/arquitetura.md +174 -0
- package/skills/acropole/references/fluxos/app-novo.md +34 -0
- package/skills/acropole/references/fluxos/tela-nova.md +1 -1
- package/skills/angular/SKILL.md +6 -3
- package/skills/angular/references/armadilhas.md +5 -1
- package/skills/angular/references/estrutura.md +33 -14
- package/skills/angular/references/testes-build.md +31 -4
- package/skills/apollo/SKILL.md +12 -8
- package/skills/apollo/references/armadilhas.md +5 -1
- package/skills/apollo/references/estrutura-bootstrap.md +47 -36
- package/skills/apollo/references/testes-build.md +12 -11
- package/skills/docker/references/porques.md +4 -0
- package/skills/express/SKILL.md +9 -7
- package/skills/express/references/estrutura.md +4 -1
- package/skills/express/references/rotas-erros.md +13 -1
- package/skills/express/references/testes-deploy.md +9 -5
- package/skills/fastapi/SKILL.md +12 -9
- package/skills/fastapi/references/banco.md +24 -12
- package/skills/fastapi/references/estrutura.md +87 -43
- package/skills/orfeu/references/diferencas.md +3 -3
- package/skills/orfeu/references/node-api.md +8 -2
- package/skills/orfeu/references/node-armadilhas.md +4 -4
- package/skills/orfeu/references/node-recipes.md +19 -12
- package/skills/orfeu/references/python.md +8 -2
- package/skills/orquestracao/SKILL.md +118 -0
- package/skills/orquestracao/references/paralelismo.md +48 -0
- package/skills/orquestracao/scripts/coord.sh +131 -0
- package/skills/orquestracao/templates/permissoes-argos.sql +28 -0
- package/skills/orquestracao/templates/plan.md +45 -0
- package/skills/orquestracao/templates/spec.md +54 -0
- package/skills/orquestracao/templates/tasks.md +21 -0
- package/skills/trismegisto/references/angular-exports.md +143 -143
|
@@ -31,14 +31,15 @@ process.on('unhandledRejection', (reason) => console.error('unhandledRejection:'
|
|
|
31
31
|
- **Atenção ao ESM**: o `import builder` é avaliado ANTES do `dotenv.config()` (imports estáticos sobem
|
|
32
32
|
primeiro). Nada no grafo de imports pode ler `process.env` em escopo de módulo — leia dentro de funções.
|
|
33
33
|
|
|
34
|
-
## `src/core/builder.ts` (padrão
|
|
34
|
+
## `src/core/builder.ts` (padrão)
|
|
35
35
|
|
|
36
36
|
```ts
|
|
37
|
+
import compression from 'compression';
|
|
37
38
|
import express from 'express';
|
|
38
39
|
import cors from 'cors';
|
|
39
40
|
import { makeExecutableSchema } from '@graphql-tools/schema';
|
|
40
41
|
import { expressMiddleware } from '@as-integrations/express4';
|
|
41
|
-
import { OrfeuClient } from '@orfeu/node';
|
|
42
|
+
import { OrfeuClient, OrfeuConfigError } from '@orfeu/node';
|
|
42
43
|
import { assertSchemaSecured, orfeuWsContext, secureResolvers } from '@orfeu/node/apollo';
|
|
43
44
|
|
|
44
45
|
import { BASE_SCHEMA } from './schema/index.js';
|
|
@@ -51,13 +52,15 @@ import { ExtendedSchema } from '../web/config/schemas/schemas.extends.js';
|
|
|
51
52
|
import type { GraphQLContext } from './context/context.types.js';
|
|
52
53
|
|
|
53
54
|
export default async (settings: NodeJS.ProcessEnv) => {
|
|
55
|
+
const tlsVerify = settings.AUTH_TLS_VERIFY !== 'false'; // opt-out; prefira NODE_EXTRA_CA_CERTS com a CA do ambiente
|
|
54
56
|
const orfeu = new OrfeuClient({
|
|
55
57
|
authorizerUrl: settings.AUTHORIZER_URL!,
|
|
56
58
|
realmId: settings.REALM_ID!,
|
|
57
59
|
appId: settings.APP_ID!,
|
|
58
60
|
secret: settings.APP_SECRET!,
|
|
59
|
-
tlsVerify
|
|
61
|
+
tlsVerify,
|
|
60
62
|
});
|
|
63
|
+
if (!tlsVerify) console.warn('AUTH_TLS_VERIFY=false: o certificado do Argos NÃO é verificado (inclusive o JWKS).');
|
|
61
64
|
|
|
62
65
|
// 1) schema seguro ANTES do startup (o startup sincroniza as operações registradas com o Argos)
|
|
63
66
|
const extended = new ExtendedSchema();
|
|
@@ -66,12 +69,27 @@ export default async (settings: NodeJS.ProcessEnv) => {
|
|
|
66
69
|
});
|
|
67
70
|
const schema = makeExecutableSchema({ typeDefs: [...BASE_SCHEMA, ...extended.typeDefs], resolvers });
|
|
68
71
|
assertSchemaSecured(schema);
|
|
69
|
-
await orfeu.startup();
|
|
70
72
|
|
|
71
|
-
// 2)
|
|
73
|
+
// 2) Orfeu: sobe e NEGA tudo até conectar, com nova tentativa de espera crescente (5 s → 30 s).
|
|
74
|
+
// Erro de configuração (OrfeuConfigError) não melhora tentando de novo: derruba a subida.
|
|
75
|
+
const status = { orfeuReady: false };
|
|
76
|
+
const startOrfeu = async (attempt = 1): Promise<void> => {
|
|
77
|
+
try {
|
|
78
|
+
await orfeu.startup();
|
|
79
|
+
status.orfeuReady = true;
|
|
80
|
+
} catch (err: any) {
|
|
81
|
+
if (err instanceof OrfeuConfigError) throw err;
|
|
82
|
+
const delay = Math.min(5_000 * 2 ** (attempt - 1), 30_000);
|
|
83
|
+
console.warn(`Orfeu indisponível (tentativa ${attempt}); operações negadas; nova tentativa em ${delay / 1000}s`);
|
|
84
|
+
setTimeout(() => void startOrfeu(attempt + 1), delay).unref();
|
|
85
|
+
}
|
|
86
|
+
};
|
|
87
|
+
await startOrfeu();
|
|
88
|
+
|
|
89
|
+
// 3) módulos (clientes REST) — criados aqui, depois do dotenv
|
|
72
90
|
const appMods = await AppModules.start(settings);
|
|
73
91
|
|
|
74
|
-
//
|
|
92
|
+
// 4) servidores: o MESMO path no HTTP e no WS
|
|
75
93
|
const graphqlPath = settings.GRAPHQL_PATH ?? '/graphql';
|
|
76
94
|
const app = express();
|
|
77
95
|
const http = new HttpServer(app);
|
|
@@ -81,9 +99,15 @@ export default async (settings: NodeJS.ProcessEnv) => {
|
|
|
81
99
|
const apollo = new ApolloServer(schema, http.server, ws.serverCleanup, orfeu);
|
|
82
100
|
await apollo.server.start();
|
|
83
101
|
|
|
84
|
-
|
|
102
|
+
// probe sem auth (rota Express, fora do Orfeu): 503 enquanto o Orfeu não conecta, 200 depois
|
|
103
|
+
app.get('/health', (_req, res) => {
|
|
104
|
+
const tls = tlsVerify ? {} : { tls_verify: false };
|
|
105
|
+
if (!status.orfeuReady) { res.status(503).json({ status: 'starting', orfeu: 'unavailable', ...tls }); return; }
|
|
106
|
+
res.status(200).json({ ok: true, ...tls });
|
|
107
|
+
});
|
|
85
108
|
app.use(
|
|
86
109
|
graphqlPath,
|
|
110
|
+
compression(), // JSON comprime 70–85%: padrão, não otimização opcional
|
|
87
111
|
cors<cors.CorsRequest>(),
|
|
88
112
|
express.json({ limit: '2mb' }),
|
|
89
113
|
expressMiddleware(apollo.server, {
|
|
@@ -94,11 +118,12 @@ export default async (settings: NodeJS.ProcessEnv) => {
|
|
|
94
118
|
const port = Number(settings.PORT ?? 3000);
|
|
95
119
|
http.server.listen(port, () => console.log(`GraphQL → http://localhost:${port}${graphqlPath}`));
|
|
96
120
|
|
|
97
|
-
//
|
|
121
|
+
// 5) encerramento: node é PID 1 no container; sem handler o stop espera o SIGKILL.
|
|
122
|
+
// Encerramento completo sai com 0; estourar o teto de 8 s sai com 1 (o orquestrador distingue).
|
|
98
123
|
for (const signal of ['SIGTERM', 'SIGINT'] as const) {
|
|
99
124
|
process.once(signal, async () => {
|
|
100
|
-
setTimeout(() => process.exit(
|
|
101
|
-
await orfeu.
|
|
125
|
+
setTimeout(() => process.exit(1), 8_000).unref();
|
|
126
|
+
await orfeu.close().catch(() => undefined); // para a recarga de permissões + envia a fila de auditoria (SDK antigo: flushAudit())
|
|
102
127
|
await apollo.server.stop().catch(() => undefined); // drain: fecha HTTP e WS
|
|
103
128
|
process.exit(0);
|
|
104
129
|
});
|
|
@@ -114,38 +139,24 @@ Pontos:
|
|
|
114
139
|
- `@orfeu/node` `^1.0.1` no `package.json` (a 1.0.0 aceitava `orfeuUser` forjado pelo `connectionParams`).
|
|
115
140
|
O contexto do WS (`ws-context.ts`, com a allowlist) está em [subscriptions.md](subscriptions.md).
|
|
116
141
|
|
|
117
|
-
### Orfeu fora do ar na subida:
|
|
118
|
-
|
|
119
|
-
Decisão do builder, explícita e comentada no código — **nunca** um "modo degradado" que libera tudo:
|
|
120
|
-
|
|
121
|
-
| Escolha | Quando | Como |
|
|
122
|
-
| --- | --- | --- |
|
|
123
|
-
| **Cai** (`exit 1`) | padrão; o orquestrador reinicia e o deploy mostra a falha | `await orfeu.startup()` sem `catch`; o `index.ts` faz `process.exit(1)` |
|
|
124
|
-
| **Sobe negando tudo** | o gateway tem rotas públicas que precisam ficar no ar, ou o Argos cai com frequência | `startup()` em segundo plano com nova tentativa; até conectar, as operações não públicas são negadas (o catálogo está vazio) |
|
|
125
|
-
|
|
126
|
-
Se subir, o `/health` responde **503 até o Orfeu conectar** — senão o deploy e o monitoramento veem
|
|
127
|
-
"saudável" um serviço que nega toda requisição:
|
|
142
|
+
### Orfeu fora do ar na subida: sobe negando (padrão)
|
|
128
143
|
|
|
129
|
-
|
|
130
|
-
let orfeuPronto = false;
|
|
131
|
-
const startOrfeu = async (attempt = 1): Promise<void> => {
|
|
132
|
-
try { await orfeu.startup(); orfeuPronto = true; }
|
|
133
|
-
catch (err: any) {
|
|
134
|
-
console.warn(`Orfeu indisponível (tentativa ${attempt}); nova tentativa em 30s:`, err.message);
|
|
135
|
-
setTimeout(() => void startOrfeu(attempt + 1), 30_000).unref();
|
|
136
|
-
}
|
|
137
|
-
};
|
|
138
|
-
void startOrfeu(); // não bloqueia a subida
|
|
144
|
+
Padrão único dos gateways — **nunca** um "modo degradado" que libera tudo, e também não cair em loop:
|
|
139
145
|
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
146
|
+
- O servidor **sobe** e o `/health` responde **503** (`{ status: 'starting', orfeu: 'unavailable' }`) até o
|
|
147
|
+
`startup()` completar; toda operação não pública é negada (401 sem token, 401/403 com token — sem JWKS e sem
|
|
148
|
+
catálogo sincronizado) e nenhuma chega ao backend.
|
|
149
|
+
- Nova tentativa com espera crescente: 5 s, 10 s, 20 s, depois a cada 30 s. Volta sozinho quando o Argos volta,
|
|
150
|
+
sem loop de restart do container.
|
|
151
|
+
- `OrfeuConfigError` (ex.: nenhuma operação registrada) **derruba** a subida: o `index.ts` sai com 1.
|
|
152
|
+
- O 503 não deve reiniciar o container: se o orquestrador tiver healthcheck ativo, ele precisa tolerar a subida.
|
|
153
|
+
- Teste obrigatório (`tests/integration/builder-falha.test.ts`): com o Orfeu fora, o servidor escuta, `/health`
|
|
154
|
+
dá 503, toda operação é negada sem chegar ao backend, e após a nova tentativa `/health` passa a 200.
|
|
144
155
|
|
|
145
156
|
O `secureResolvers` e o `assertSchemaSecured` continuam **antes** de qualquer tentativa (o catálogo precisa
|
|
146
157
|
estar registrado quando o `startup()` sincronizar).
|
|
147
158
|
|
|
148
|
-
- `compression()` antes do Apollo
|
|
159
|
+
- `compression()` antes do Apollo em todo gateway (JSON comprime 70–85%; respostas de vários MB caem para centenas de KB).
|
|
149
160
|
|
|
150
161
|
## `src/core/server/*.ts`
|
|
151
162
|
|
|
@@ -83,20 +83,20 @@ Validação focada: rode os testes do que mudou e `npm run typecheck`.
|
|
|
83
83
|
|
|
84
84
|
## Build
|
|
85
85
|
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
| `tsc` (recomendada para servidores novos) | `"build": "tsc"` | `module`/`moduleResolution: NodeNext`, `strict: true`, imports relativos com `.js` |
|
|
91
|
-
| `esbuild` bundle | `esbuild src/index.ts --bundle --platform=node --format=esm --packages=external --target=es2022 --sourcemap --outfile=dist/index.js` | rápido; **não** checa tipos → `"typecheck": "tsc --noEmit"` obrigatório |
|
|
86
|
+
Padrão: **`typecheck` + bundle com esbuild** no mesmo script de build. O esbuild gera um arquivo só em
|
|
87
|
+
milissegundos (build de imagem mais rápido, subida sem resolver centenas de módulos) mas **não** checa tipos —
|
|
88
|
+
por isso o `build` roda o `tsc --noEmit` antes, e um erro de tipo nunca chega à imagem. Código que lê arquivo
|
|
89
|
+
relativo ao `dist/` em runtime (`readFileSync`, `__dirname`) quebra no bundle: confira antes de migrar.
|
|
92
90
|
|
|
93
91
|
```json
|
|
94
92
|
{
|
|
95
93
|
"type": "module",
|
|
96
94
|
"scripts": {
|
|
97
95
|
"dev": "cross-env NODE_ENV=local tsx watch src/index.ts",
|
|
96
|
+
"start": "cross-env NODE_ENV=local tsx src/index.ts",
|
|
98
97
|
"start:local": "cross-env NODE_ENV=local tsx watch src/index.ts",
|
|
99
|
-
"
|
|
98
|
+
"start:homol": "cross-env NODE_ENV=homol tsx watch src/index.ts",
|
|
99
|
+
"build": "npm run typecheck && esbuild src/index.ts --bundle --platform=node --format=esm --packages=external --target=es2022 --tsconfig=tsconfig.json --sourcemap --outfile=dist/index.js",
|
|
100
100
|
"typecheck": "tsc --noEmit",
|
|
101
101
|
"start:prod": "node dist/index.js",
|
|
102
102
|
"test": "vitest run"
|
|
@@ -105,8 +105,9 @@ Duas formas em uso — escolha uma por servidor e mantenha o `typecheck`:
|
|
|
105
105
|
```
|
|
106
106
|
|
|
107
107
|
`tsconfig`: `target ES2022`, `module NodeNext`, `strict`, `esModuleInterop`, `skipLibCheck`, `outDir dist`,
|
|
108
|
-
`rootDir src`.
|
|
109
|
-
|
|
108
|
+
`rootDir src`. Imports relativos com `.js` (o esbuild também resolveria alias `src/*`, mas relativo funciona
|
|
109
|
+
igual no `tsx`, no `vitest` e no `tsc`). Dependências com faixa explícita da versão em uso (`^16.14.2`, não
|
|
110
|
+
`^16`); `@types/node` na major do Node da imagem (`node:22` → `^22`).
|
|
110
111
|
|
|
111
112
|
## Migração Apollo Server 4 → 5
|
|
112
113
|
|
|
@@ -159,9 +160,9 @@ CMD ["node", "dist/index.js"]
|
|
|
159
160
|
| `PORT` | porta HTTP/WS |
|
|
160
161
|
| `GRAPHQL_PATH` | path do GraphQL **e** do WS (`/graphql`, ou `/<app>/graphql` atrás de proxy) |
|
|
161
162
|
| `AUTHORIZER_URL`, `REALM_ID`, `APP_ID`, `APP_SECRET` | `OrfeuClient` (app registrado no Argos) |
|
|
162
|
-
| `AUTH_TLS_VERIFY` | `false` só se a CA do Argos não está no bundle do Node |
|
|
163
|
+
| `AUTH_TLS_VERIFY` | `false` só se a CA do Argos não está no bundle do Node (prefira `NODE_EXTRA_CA_CERTS`); loga aviso e aparece no `/health` |
|
|
163
164
|
| `PLATFORM_SERVICE_URL` (ou `<SERVICO>_URL`) | `baseURL` dos módulos REST |
|
|
164
|
-
| `REDIS_HOST`, `REDIS_PORT`, `REDIS_PASSWORD`, `REDIS_DB`, `REDIS_CHANNEL_PREFIX` | pub/sub |
|
|
165
|
+
| `REDIS_HOST`, `REDIS_PORT`, `REDIS_PASSWORD`, `REDIS_DB`, `REDIS_CHANNEL_PREFIX` | pub/sub; `REDIS_DB` próprio do app (nunca o mesmo de outro app no mesmo Redis), igual ao do server do app |
|
|
165
166
|
| `REDIS_CLUSTER`, `REDIS_HOSTS` | modo cluster |
|
|
166
167
|
| `GRAPHQL_INTROSPECTION` | `true` só onde se roda o codegen |
|
|
167
168
|
|
|
@@ -198,6 +198,10 @@ Faz o engine marcar o container como `healthy`/`unhealthy` (visível no inventá
|
|
|
198
198
|
instale `curl` só para isso.
|
|
199
199
|
- Chame `127.0.0.1`, não o domínio, e inclua o prefixo do app no path.
|
|
200
200
|
- `--start-period` cobre a subida (conexões, registro no Argos).
|
|
201
|
+
- Gateway GraphQL responde **503** no `/health` enquanto o Orfeu não conecta (sobe negando tudo e tenta de
|
|
202
|
+
novo): `unhealthy` nesse período é informação, não motivo para reiniciar. Docker/Podman puros só marcam o
|
|
203
|
+
estado; se o orquestrador reinicia container `unhealthy`, dê `--start-period`/`--retries` folgados para não
|
|
204
|
+
transformar Argos fora do ar em loop de restart.
|
|
201
205
|
- **Podman/Buildah** gravam `HEALTHCHECK` apenas em imagem formato `docker`; no formato OCI (padrão)
|
|
202
206
|
a instrução é descartada com aviso. E o deploy não espera `healthy` para concluir. Na prática o
|
|
203
207
|
`/health` do app é o que importa: é ele que você consulta depois do deploy (ver **hefesto**).
|
package/skills/express/SKILL.md
CHANGED
|
@@ -46,11 +46,13 @@ Skills relacionadas (não duplicamos o conteúdo delas):
|
|
|
46
46
|
9. **Chamadas a outros serviços repassam credencial e trace** (`orfeuHeaders(ctx)` dentro do contexto
|
|
47
47
|
do Orfeu; repasse explícito dos headers nas rotas que não passam por ele). Nunca gere um span
|
|
48
48
|
próprio que ninguém audita.
|
|
49
|
-
10. **Graceful shutdown** em `SIGTERM`/`SIGINT`: timer de segurança `unref()
|
|
50
|
-
Orfeu, `server.close()
|
|
51
|
-
`npm start`.
|
|
49
|
+
10. **Graceful shutdown** em `SIGTERM`/`SIGINT`: timer de segurança `unref()` (8 s, sai com **1**),
|
|
50
|
+
`flushAudit()` do Orfeu, `server.close()` (sai com **0**). No container o `node` é PID 1 e roda direto
|
|
51
|
+
(`CMD ["node", …]`), nunca via `npm start`.
|
|
52
52
|
11. **Health check** em `GET <prefixo>/health`: verifica as dependências reais (`SELECT 1`, `PING`) com
|
|
53
|
-
`Promise.allSettled` e responde `200`/`503` com o estado de cada uma
|
|
53
|
+
`Promise.allSettled` e responde `200`/`503` com o estado de cada uma (+ `tls_verify: false` quando
|
|
54
|
+
`AUTH_TLS_VERIFY=false`). **Swagger (`<prefixo>/docs`) só com `API_DOCS`**, que por padrão liga só em
|
|
55
|
+
`NODE_ENV=local`. Padrão do app inteiro: skill `acropole` (`references/arquitetura.md`).
|
|
54
56
|
12. **Logs JSON de uma linha** em produção (`{ time, level, msg, ...ctx }`), coloridos só em dev;
|
|
55
57
|
nunca logar token, senha, segredo ou corpo de requisição de autenticação.
|
|
56
58
|
13. **Rota escopada por recurso pai** (`/:clientId/...`) confere a posse de **todo** id da URL e do corpo
|
|
@@ -86,9 +88,9 @@ export default async (settings: EnvConfig) => {
|
|
|
86
88
|
const server = await Server.start(settings);
|
|
87
89
|
for (const sig of ['SIGTERM', 'SIGINT'] as const) {
|
|
88
90
|
process.once(sig, async () => {
|
|
89
|
-
setTimeout(() => process.exit(
|
|
90
|
-
await orfeuClient.
|
|
91
|
-
server.http.close(() => process.exit(0));
|
|
91
|
+
setTimeout(() => process.exit(1), 8_000).unref(); // teto estourado = falha (1)
|
|
92
|
+
await orfeuClient.close().catch(() => undefined); // recarga de permissões + auditoria (SDK antigo: flushAudit())
|
|
93
|
+
server.http.close(() => process.exit(0)); // encerramento completo = 0
|
|
92
94
|
});
|
|
93
95
|
}
|
|
94
96
|
return server;
|
|
@@ -131,7 +131,10 @@ Variáveis recorrentes (só nomes): `API_PREFIX`, `PORT`/`AGENT_PORT`, `DB_*`, `
|
|
|
131
131
|
`SMTP_*`, `UI_STATIC_PATH`, `UI_BASE_PATH`, `GRAPHQL_PATH`, `GRAPHQL_INTROSPECTION`.
|
|
132
132
|
|
|
133
133
|
- `AUTH_TLS_VERIFY=false` existe só para ambiente com certificado autoassinado; é opção **escopada ao
|
|
134
|
-
client do Orfeu**, nunca `NODE_TLS_REJECT_UNAUTHORIZED=0` global.
|
|
134
|
+
client do Orfeu**, nunca `NODE_TLS_REJECT_UNAUTHORIZED=0` global. Desligada, loga um aviso na subida e
|
|
135
|
+
aparece como `tls_verify: false` no `/health`. Prefira `NODE_EXTRA_CA_CERTS` com a CA do ambiente.
|
|
136
|
+
- `API_DOCS` (opcional): liga/desliga o Swagger; sem ela, só em `NODE_ENV=local`.
|
|
137
|
+
- `@types/node` na major do Node da imagem (`node:22` → `^22`).
|
|
135
138
|
- Booleans de env: compare com string (`v !== 'false'`), não `Boolean(v)` (`"false"` é truthy).
|
|
136
139
|
- Arquivos `.env` cifrados (dotenvx) podem ir ao repositório; a chave de decifrar fica fora dele.
|
|
137
140
|
Arquivo de `.env` em texto puro nunca é versionado.
|
|
@@ -271,4 +271,16 @@ export function decodeCursor(raw: string) {
|
|
|
271
271
|
## Documentação
|
|
272
272
|
|
|
273
273
|
OpenAPI em `src/config/openapi.ts` servido por `swagger-ui-express` em `<prefixo>/docs`, com um CSP
|
|
274
|
-
próprio para essa rota (o CSP global da API é `default-src 'none'`).
|
|
274
|
+
próprio para essa rota (o CSP global da API é `default-src 'none'`). **Só monte a rota com `config.API_DOCS`**:
|
|
275
|
+
o mapa da API não fica exposto sem autenticação nos ambientes publicados.
|
|
276
|
+
|
|
277
|
+
```ts
|
|
278
|
+
// config/index.ts (zod): sem API_DOCS, liga só em NODE_ENV=local (o container roda com outro NODE_ENV)
|
|
279
|
+
API_DOCS: z.enum(['true', 'false']).optional()
|
|
280
|
+
.transform((v) => (v === undefined ? process.env.NODE_ENV === 'local' : v === 'true')),
|
|
281
|
+
|
|
282
|
+
// router.ts
|
|
283
|
+
if (config.API_DOCS) router.use('/docs', cspDaDocumentacao, swaggerUi.serve, swaggerUi.setup(openApiSpec));
|
|
284
|
+
```
|
|
285
|
+
|
|
286
|
+
Teste do config: `NODE_ENV=dev`/`test` → `false`; `local` → `true`; `API_DOCS` força nos dois sentidos.
|
|
@@ -36,7 +36,8 @@ router.get('/health', async (_req, res) => {
|
|
|
36
36
|
const postgres = pg.status === 'fulfilled' ? 'ok' : 'error';
|
|
37
37
|
const cacheSt = redis.status === 'fulfilled' ? 'ok' : 'error';
|
|
38
38
|
const status = postgres === 'ok' && cacheSt === 'ok' ? 'ok' : 'degraded';
|
|
39
|
-
|
|
39
|
+
const tls = config.AUTH_TLS_VERIFY ? {} : { tls_verify: false }; // TLS do autorizador desligado: visível
|
|
40
|
+
res.status(status === 'ok' ? 200 : 503).json({ status, postgres, redis: cacheSt, ...tls });
|
|
40
41
|
});
|
|
41
42
|
```
|
|
42
43
|
|
|
@@ -48,16 +49,19 @@ router.get('/health', async (_req, res) => {
|
|
|
48
49
|
## Graceful shutdown
|
|
49
50
|
|
|
50
51
|
```ts
|
|
51
|
-
for (const
|
|
52
|
+
for (const sig of ['SIGTERM', 'SIGINT'] as const) {
|
|
52
53
|
process.once(sig, async () => {
|
|
53
54
|
Logger.info('Encerrando', { signal: sig });
|
|
54
|
-
setTimeout(() => process.exit(
|
|
55
|
-
try { await orfeuClient.
|
|
56
|
-
httpServer.close(() => process.exit(
|
|
55
|
+
setTimeout(() => process.exit(1), 8_000).unref(); // teto estourado = falha
|
|
56
|
+
try { await orfeuClient.close(); } catch (err: any) { Logger.warn('encerramento do Orfeu falhou', { message: err?.message }); } // SDK antigo: flushAudit()
|
|
57
|
+
httpServer.close(() => process.exit(0)); // encerramento completo = sucesso
|
|
57
58
|
});
|
|
58
59
|
}
|
|
59
60
|
```
|
|
60
61
|
|
|
62
|
+
- Mesma convenção em todo serviço Node do ecossistema: **0** quando drenou, **1** quando o teto estourou —
|
|
63
|
+
o orquestrador distingue parada limpa de travamento (o 143/130 do shell não diz se a drenagem completou).
|
|
64
|
+
|
|
61
65
|
- `flushAudit()` de **cada** `OrfeuClient` instanciado (`Promise.allSettled`).
|
|
62
66
|
- Com Apollo, `ApolloServerPluginDrainHttpServer` + dispose do servidor WebSocket (apollo).
|
|
63
67
|
- Feche também pool do Knex (`db.destroy()`) e Redis (`quit()`) se o encerramento puder demorar.
|
package/skills/fastapi/SKILL.md
CHANGED
|
@@ -19,10 +19,9 @@ orfeu — não duplique aqui.
|
|
|
19
19
|
|
|
20
20
|
1. **Python ≥ 3.11** (piso do `orfeu` e da imagem `python:3.11-slim`). FastAPI recente (≥ 0.142) e
|
|
21
21
|
Starlette 1.x: **só `lifespan`** — `on_event`/`add_event_handler` não existem mais.
|
|
22
|
-
2. **Dependências em `requirements.txt` + `requirements-dev.txt
|
|
23
|
-
É o que o Dockerfile instala.
|
|
24
|
-
|
|
25
|
-
`orfeu[fastapi]` numa versão exata ou faixa `>=1.0,<2`.
|
|
22
|
+
2. **Dependências em `requirements.txt` + `requirements-dev.txt`**: só as **diretas**, cada uma com
|
|
23
|
+
**versão exata** (`fastapi==0.142.2`), `uvicorn[standard]`. É o que o Dockerfile instala. `pyproject.toml`
|
|
24
|
+
só com os atalhos do `poe` (`start:local|dev|homol`, `test`) — nada de Poetry em paralelo.
|
|
26
25
|
3. **Estrutura por domínio**: `src/app/domains/<domínio>/{router,schemas,service,repository,models}.py`.
|
|
27
26
|
Router fino → service (regra, levanta erros do Orfeu, não conhece HTTP) → repository (SQLAlchemy, sem
|
|
28
27
|
regra). Um domínio usa outro **só pelo service**. Ver [references/estrutura.md](references/estrutura.md).
|
|
@@ -44,7 +43,7 @@ orfeu — não duplique aqui.
|
|
|
44
43
|
síncrona devem ser `def` (rodam no threadpool), não `async def`. Ver
|
|
45
44
|
[references/banco.md](references/banco.md).
|
|
46
45
|
9. **Schema do banco fora do ORM**: pasta `database/` irmã do serviço com `manifest.yml` + `scripts/
|
|
47
|
-
{delete,create,insert}` + `build.py` (gera `output/build.sql`, `--exec` aplica) + `migrations/NNN-*.sql`
|
|
46
|
+
{bootstrap,delete,create,insert,migrations}` + `build.py` (gera `output/build.sql`, `--exec` aplica) + `scripts/migrations/NNN-*.sql`
|
|
48
47
|
manuais. Não há Alembic nem `create_all` em produção.
|
|
49
48
|
10. **Configuração por ambiente**: `pydantic-settings` + `src/.env` (só `APP_ENV`) +
|
|
50
49
|
`src/settings/environment/.env.<APP_ENV>`; variáveis do processo vencem os arquivos. Nunca versione
|
|
@@ -99,12 +98,16 @@ def create_tag(body: TagCreate, db: Session = Depends(get_db)):
|
|
|
99
98
|
código novo passe `method=Method.X` explícito (regra da orfeu).
|
|
100
99
|
- Proxy reverso que encaminha o path completo (sem strip): o serviço precisa montar rotas **e**
|
|
101
100
|
`docs_url`/`openapi_url`/`redoc_url` sob `api_prefix` (`/<projeto>/server`).
|
|
102
|
-
- `/docs`, `/openapi.json` e `/redoc`
|
|
103
|
-
`None` nos três
|
|
104
|
-
- `AUTHORIZER_TLS_VERIFY=false` (TLS do autorizador desligado)
|
|
105
|
-
|
|
101
|
+
- `/docs`, `/openapi.json` e `/redoc` expõem o mapa da API: ligados **só em `APP_ENV=local`** (`API_DOCS`
|
|
102
|
+
força); `fastapi_kwargs` passa `None` nos três fora disso ([references/estrutura.md](references/estrutura.md)).
|
|
103
|
+
- `AUTHORIZER_TLS_VERIFY=false` (TLS do autorizador desligado): `warning` na subida e `tls_verify: false` no
|
|
104
|
+
`/health`. `urllib3.disable_warnings` no processo inteiro esconde isso — use aviso uma vez por host.
|
|
105
|
+
- `/health` (envelope `ok(message="ok")` sob o `api_prefix`) em todo serviço. Padrão do app inteiro (pastas,
|
|
106
|
+
portas, ambientes, scripts): skill `acropole` (`references/arquitetura.md`).
|
|
106
107
|
- Campo de settings não declarado entrando via `extra="allow"` (ex.: porta) funciona por acaso — declare
|
|
107
108
|
todo campo usado.
|
|
109
|
+
- `request.state.user` é o `TokenClaims` do Orfeu (objeto: `.sub`, `.groups`, `.raw`), não `dict`: `.get()` dá
|
|
110
|
+
500. Nome em `user.raw.get("preferred_username")`; com `x-api-token` o user é `None` (`request.state.api_token`).
|
|
108
111
|
- Tarefa em segundo plano não pode usar a sessão da requisição (já fechada): abra outra a partir de
|
|
109
112
|
`app.state.SessionLocal`.
|
|
110
113
|
- `CMD` do container com `exec uvicorn ...` — sem `exec`, o `sh` vira PID 1, não repassa SIGTERM e todo
|
|
@@ -132,22 +132,34 @@ execução aborta num script que nem tem parâmetros. Soluções:
|
|
|
132
132
|
|
|
133
133
|
## Pasta `database/` (build do schema)
|
|
134
134
|
|
|
135
|
+
Mesma estrutura em todo app, ao lado de `angular/`, `graphql/` e `server/`. `build.py`, `tools/`, `tests/` (menos
|
|
136
|
+
`test_app.py`), `.gitignore`, `pytest.ini` e `requirements*.txt` são **idênticos byte a byte** entre os apps:
|
|
137
|
+
mudança neles vale para todos (copie para os outros e rode a suíte de cada um). O que é do app fica só em
|
|
138
|
+
`manifest.yml`, `env/`, `scripts/`, `tests/test_app.py` e nas seções "Schemas" e "Particularidades" do
|
|
139
|
+
`CLAUDE.md` da pasta. Um teste de estrutura falha se aparecer pasta ou arquivo fora do padrão.
|
|
140
|
+
|
|
135
141
|
```
|
|
136
142
|
database/
|
|
137
|
-
manifest.yml ordem dos arquivos por fase: delete / create / insert
|
|
138
|
-
build.py scripts/ → output/build.sql; --exec aplica; --reset inclui delete; --seed só insert
|
|
143
|
+
manifest.yml ordem dos arquivos por fase: delete / create / insert (insert pode ser [] num app novo)
|
|
144
|
+
build.py scripts/ → output/build.sql; --exec aplica; --reset inclui delete; --seed só insert;
|
|
145
|
+
--bootstrap cria role+database (lê a senha do ambiente, nunca grava)
|
|
139
146
|
requirements.txt python-dotenv, PyYAML, SQLAlchemy, psycopg2-binary
|
|
140
|
-
env/.env(.example) POSTGRESQL_HOST
|
|
147
|
+
env/.env(.example) POSTGRESQL_HOST/PORT/DATABASE/USER/PASSWORD (+ POSTGRESQL_SUPERUSER(_PASSWORD) do bootstrap)
|
|
141
148
|
scripts/
|
|
142
|
-
bootstrap/
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
+
bootstrap/00-create-db.sql CREATE ROLE <app> + CREATE DATABASE <app> + REVOKE CONNECT FROM PUBLIC;
|
|
150
|
+
senha só por variável do psql (:'role_password'), nunca literal
|
|
151
|
+
delete/reset.sql DROP SCHEMA IF EXISTS <schemas> CASCADE — só com --reset (dev/homol/CI)
|
|
152
|
+
create/<schema>/NN-*.sql forma FINAL das tabelas (CREATE TABLE sem IF NOT EXISTS)
|
|
153
|
+
insert/<schema>/<tabela>.sql seed idempotente, um arquivo por tabela
|
|
154
|
+
migrations/NNN-descricao.sql histórico de ALTER aplicado manualmente (subpasta = DDL de outro banco)
|
|
155
|
+
output/build.sql gerado e versionado (um teste confere que está em dia); não editar
|
|
156
|
+
tools/ sync_from_db.py (regera insert/ de um banco) e compare_db.py (compara dois bancos)
|
|
157
|
+
tests/ pytest sem rede nem banco real; tests/pg = PGlite (Postgres em memória) para os testes de SQL
|
|
149
158
|
```
|
|
150
159
|
|
|
160
|
+
App novo começa com o schema criado e sem tabela, seed nem migration: os testes compartilhados aceitam isso
|
|
161
|
+
(pulam as checagens que dependem de tabela/migration) e passam a valer a partir da primeira.
|
|
162
|
+
|
|
151
163
|
Uso:
|
|
152
164
|
|
|
153
165
|
```bash
|
|
@@ -162,7 +174,7 @@ Regras:
|
|
|
162
174
|
- `create/` sem `IF NOT EXISTS` (exceto `CREATE SCHEMA`): rodar duas vezes sem `--reset` falha de
|
|
163
175
|
propósito — impede aplicar create em banco vivo por engano.
|
|
164
176
|
- **Toda mudança de schema em produção = duas coisas**: editar `create/` para a forma final **e** escrever
|
|
165
|
-
`migrations/NNN-*.sql` com o `ALTER` real (cabeçalho com data, dependência e aviso se destrutivo; tudo
|
|
177
|
+
`scripts/migrations/NNN-*.sql` com o `ALTER` real (cabeçalho com data, dependência e aviso se destrutivo; tudo
|
|
166
178
|
numa transação). `build.py` não aplica migrations.
|
|
167
179
|
- Seed: `ON CONFLICT ... DO NOTHING` para dado que a UI edita (não sobrescreve); `ON CONFLICT (pk) DO
|
|
168
180
|
UPDATE` com UUID literal para dado de referência controlado pelo código. Conflito sempre na PK ou numa
|
|
@@ -179,7 +191,7 @@ Divergências observadas:
|
|
|
179
191
|
|
|
180
192
|
| Tema | Visto | Recomendado |
|
|
181
193
|
|---|---|---|
|
|
182
|
-
| Migrations |
|
|
194
|
+
| Migrations | fora de `database/` ou misturando SQL e script Python | `database/scripts/migrations/NNN-*.sql`; scripts de dados pontuais em `database/tools/` |
|
|
183
195
|
| `build.py` | versões com e sem `--seed`, relatório de erro e `newline=""` | a versão completa acima |
|
|
184
196
|
| Seed | `DO NOTHING` por nome vs `DO UPDATE` por PK literal | regra da lista acima |
|
|
185
197
|
| Commit | no repository (todos) | `flush` no repository, `commit` no service quando a operação tem várias escritas |
|