@acropole/skills 0.0.0-stage → 1.0.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 +180 -2
- package/agents/revisor-deploy.md +73 -0
- package/agents/revisor-documentacao.md +78 -0
- package/agents/revisor-orfeu.md +80 -0
- package/agents/revisor-trismegisto.md +81 -0
- package/bin/install.js +252 -0
- package/package.json +15 -4
- package/skills/acropole/SKILL.md +75 -0
- package/skills/acropole/references/fluxos/doctor.md +55 -0
- package/skills/acropole/references/fluxos/endpoint-novo.md +22 -0
- package/skills/acropole/references/fluxos/revisar.md +56 -0
- package/skills/acropole/references/fluxos/tela-nova.md +27 -0
- package/skills/acropole/scripts/doctor.mjs +439 -0
- package/skills/angular/SKILL.md +152 -0
- package/skills/angular/references/armadilhas.md +95 -0
- package/skills/angular/references/dados.md +251 -0
- package/skills/angular/references/estrutura.md +260 -0
- package/skills/angular/references/features.md +219 -0
- package/skills/angular/references/testes-build.md +230 -0
- package/skills/angular/scripts/checar.mjs +182 -0
- package/skills/angular/scripts/nucleo.mjs +227 -0
- package/skills/apollo/SKILL.md +222 -0
- package/skills/apollo/references/armadilhas.md +95 -0
- package/skills/apollo/references/envelope-erros.md +120 -0
- package/skills/apollo/references/estrutura-bootstrap.md +299 -0
- package/skills/apollo/references/schema-resolvers.md +183 -0
- package/skills/apollo/references/subscriptions.md +224 -0
- package/skills/apollo/references/testes-build.md +180 -0
- package/skills/apollo/scripts/checar.mjs +160 -0
- package/skills/apollo/scripts/nucleo.mjs +227 -0
- package/skills/docker/SKILL.md +102 -0
- package/skills/docker/references/modelos.md +251 -0
- package/skills/docker/references/porques.md +282 -0
- package/skills/documentacao/SKILL.md +146 -0
- package/skills/documentacao/references/checklist-coerencia.md +59 -0
- package/skills/documentacao/references/ligar-app-novo.md +107 -0
- package/skills/documentacao/references/modelo-especificacao.md +51 -0
- package/skills/documentacao/references/modelo-readme.md +75 -0
- package/skills/documentacao/scripts/checar.mjs +454 -0
- package/skills/documentacao/scripts/nucleo.mjs +227 -0
- package/skills/express/SKILL.md +154 -0
- package/skills/express/references/dados.md +180 -0
- package/skills/express/references/estrutura.md +154 -0
- package/skills/express/references/middlewares.md +227 -0
- package/skills/express/references/rotas-erros.md +274 -0
- package/skills/express/references/testes-deploy.md +150 -0
- package/skills/express/scripts/checar.mjs +115 -0
- package/skills/express/scripts/nucleo.mjs +227 -0
- package/skills/fastapi/SKILL.md +129 -0
- package/skills/fastapi/references/banco.md +185 -0
- package/skills/fastapi/references/estrutura.md +281 -0
- package/skills/fastapi/references/integracoes.md +145 -0
- package/skills/fastapi/references/rotas-erros.md +140 -0
- package/skills/fastapi/references/testes-deploy.md +190 -0
- package/skills/fastapi/scripts/checar.mjs +108 -0
- package/skills/fastapi/scripts/nucleo.mjs +227 -0
- package/skills/hefesto/SKILL.md +119 -0
- package/skills/hefesto/references/conceitos.md +131 -0
- package/skills/hefesto/references/diagnostico.md +70 -0
- package/skills/hefesto/references/fluxo.md +122 -0
- package/skills/hefesto/references/preparar-app.md +105 -0
- package/skills/orfeu/SKILL.md +162 -0
- package/skills/orfeu/references/angular-api.md +201 -0
- package/skills/orfeu/references/angular-armadilhas.md +116 -0
- package/skills/orfeu/references/angular-recipes.md +474 -0
- package/skills/orfeu/references/angular.md +212 -0
- package/skills/orfeu/references/diferencas.md +56 -0
- package/skills/orfeu/references/node-api.md +348 -0
- package/skills/orfeu/references/node-armadilhas.md +158 -0
- package/skills/orfeu/references/node-recipes.md +534 -0
- package/skills/orfeu/references/node.md +204 -0
- package/skills/orfeu/references/python-api.md +346 -0
- package/skills/orfeu/references/python-recipes.md +479 -0
- package/skills/orfeu/references/python.md +234 -0
- package/skills/orfeu/scripts/checar.mjs +126 -0
- package/skills/orfeu/scripts/nucleo.mjs +227 -0
- package/skills/trismegisto/SKILL.md +194 -0
- package/skills/trismegisto/references/angular-api.md +2788 -0
- package/skills/trismegisto/references/angular-exports.md +4020 -0
- package/skills/trismegisto/references/angular-recipes.md +1883 -0
- package/skills/trismegisto/references/angular-types.md +492 -0
- package/skills/trismegisto/references/angular.md +390 -0
- package/skills/trismegisto/references/catalogo/icones.json +912 -0
- package/skills/trismegisto/references/catalogo/seletores.json +7013 -0
- package/skills/trismegisto/references/catalogo/tokens.json +240 -0
- package/skills/trismegisto/references/spine-api.md +1530 -0
- package/skills/trismegisto/references/spine-recipes.md +581 -0
- package/skills/trismegisto/references/spine.md +343 -0
- package/skills/trismegisto/scripts/checar.mjs +216 -0
- package/skills/trismegisto/scripts/nucleo.mjs +227 -0
|
@@ -0,0 +1,299 @@
|
|
|
1
|
+
# Estrutura e bootstrap
|
|
2
|
+
|
|
3
|
+
O servidor é **Apollo Server montado no Express** (`expressMiddleware`), não o modo standalone: o mesmo
|
|
4
|
+
`http.Server` serve o GraphQL (HTTP), o WebSocket das subscriptions e, quando preciso, rotas REST auxiliares
|
|
5
|
+
(upload, proxy de arquivo). Express em si: **express**.
|
|
6
|
+
|
|
7
|
+
## `src/index.ts`
|
|
8
|
+
|
|
9
|
+
```ts
|
|
10
|
+
console.time('Server | Load Time');
|
|
11
|
+
|
|
12
|
+
import * as dotenv from 'dotenv';
|
|
13
|
+
dotenv.config({ path: `src/settings/environment/.env.${process.env.NODE_ENV ?? 'local'}` });
|
|
14
|
+
|
|
15
|
+
import builder from './core/builder.js';
|
|
16
|
+
|
|
17
|
+
try {
|
|
18
|
+
await builder(process.env);
|
|
19
|
+
} catch (error) {
|
|
20
|
+
console.error('Falha na subida:', error);
|
|
21
|
+
process.exit(1); // sem isto o processo fica de pé sem servir nada
|
|
22
|
+
}
|
|
23
|
+
console.timeEnd('Server | Load Time');
|
|
24
|
+
|
|
25
|
+
process.on('unhandledRejection', (reason) => console.error('unhandledRejection:', reason));
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
- `NODE_ENV` com padrão (`?? 'local'`): sem ele o dotenv procura `.env.undefined`.
|
|
29
|
+
- No container o `.env.*` não é copiado (só `dist/`): as variáveis vêm do ambiente do container e o
|
|
30
|
+
`dotenv.config` simplesmente não acha o arquivo — é o esperado.
|
|
31
|
+
- **Atenção ao ESM**: o `import builder` é avaliado ANTES do `dotenv.config()` (imports estáticos sobem
|
|
32
|
+
primeiro). Nada no grafo de imports pode ler `process.env` em escopo de módulo — leia dentro de funções.
|
|
33
|
+
|
|
34
|
+
## `src/core/builder.ts` (padrão recomendado)
|
|
35
|
+
|
|
36
|
+
```ts
|
|
37
|
+
import express from 'express';
|
|
38
|
+
import cors from 'cors';
|
|
39
|
+
import { makeExecutableSchema } from '@graphql-tools/schema';
|
|
40
|
+
import { expressMiddleware } from '@as-integrations/express4';
|
|
41
|
+
import { OrfeuClient } from '@orfeu/node';
|
|
42
|
+
import { assertSchemaSecured, orfeuWsContext, secureResolvers } from '@orfeu/node/apollo';
|
|
43
|
+
|
|
44
|
+
import { BASE_SCHEMA } from './schema/index.js';
|
|
45
|
+
import { HttpServer } from './server/http.server.js';
|
|
46
|
+
import { WsServer } from './server/ws.server.js';
|
|
47
|
+
import { ApolloServer } from './server/apollo.server.js';
|
|
48
|
+
import { wsContextParams } from './context/ws-context.js';
|
|
49
|
+
import { AppModules } from '../web/config/index.js';
|
|
50
|
+
import { ExtendedSchema } from '../web/config/schemas/schemas.extends.js';
|
|
51
|
+
import type { GraphQLContext } from './context/context.types.js';
|
|
52
|
+
|
|
53
|
+
export default async (settings: NodeJS.ProcessEnv) => {
|
|
54
|
+
const orfeu = new OrfeuClient({
|
|
55
|
+
authorizerUrl: settings.AUTHORIZER_URL!,
|
|
56
|
+
realmId: settings.REALM_ID!,
|
|
57
|
+
appId: settings.APP_ID!,
|
|
58
|
+
secret: settings.APP_SECRET!,
|
|
59
|
+
tlsVerify: settings.AUTH_TLS_VERIFY !== 'false', // opt-out; só para CA fora do bundle do Node
|
|
60
|
+
});
|
|
61
|
+
|
|
62
|
+
// 1) schema seguro ANTES do startup (o startup sincroniza as operações registradas com o Argos)
|
|
63
|
+
const extended = new ExtendedSchema();
|
|
64
|
+
const resolvers = secureResolvers(orfeu, extended.resolvers, {
|
|
65
|
+
onForbidden: () => ({ status: 403, message: 'Você não tem permissão para esta operação.', data: null }),
|
|
66
|
+
});
|
|
67
|
+
const schema = makeExecutableSchema({ typeDefs: [...BASE_SCHEMA, ...extended.typeDefs], resolvers });
|
|
68
|
+
assertSchemaSecured(schema);
|
|
69
|
+
await orfeu.startup();
|
|
70
|
+
|
|
71
|
+
// 2) módulos (clientes REST) — criados aqui, depois do dotenv
|
|
72
|
+
const appMods = await AppModules.start(settings);
|
|
73
|
+
|
|
74
|
+
// 3) servidores: o MESMO path no HTTP e no WS
|
|
75
|
+
const graphqlPath = settings.GRAPHQL_PATH ?? '/graphql';
|
|
76
|
+
const app = express();
|
|
77
|
+
const http = new HttpServer(app);
|
|
78
|
+
// extra do WS: módulos + só a allowlist do connectionParams (nunca `...connectionParams`)
|
|
79
|
+
const ws = new WsServer(http.server, schema,
|
|
80
|
+
orfeuWsContext(orfeu, (ctx) => ({ App: appMods, ...wsContextParams(ctx) })), graphqlPath);
|
|
81
|
+
const apollo = new ApolloServer(schema, http.server, ws.serverCleanup, orfeu);
|
|
82
|
+
await apollo.server.start();
|
|
83
|
+
|
|
84
|
+
app.get('/health', (_req, res) => { res.status(200).json({ ok: true }); }); // probe sem auth (aqui o startup já passou)
|
|
85
|
+
app.use(
|
|
86
|
+
graphqlPath,
|
|
87
|
+
cors<cors.CorsRequest>(),
|
|
88
|
+
express.json({ limit: '2mb' }),
|
|
89
|
+
expressMiddleware(apollo.server, {
|
|
90
|
+
context: async ({ req }): Promise<GraphQLContext> => ({ App: appMods, req }),
|
|
91
|
+
}),
|
|
92
|
+
);
|
|
93
|
+
|
|
94
|
+
const port = Number(settings.PORT ?? 3000);
|
|
95
|
+
http.server.listen(port, () => console.log(`GraphQL → http://localhost:${port}${graphqlPath}`));
|
|
96
|
+
|
|
97
|
+
// 4) encerramento: node é PID 1 no container; sem handler o stop espera o SIGKILL
|
|
98
|
+
for (const signal of ['SIGTERM', 'SIGINT'] as const) {
|
|
99
|
+
process.once(signal, async () => {
|
|
100
|
+
setTimeout(() => process.exit(0), 8_000).unref();
|
|
101
|
+
await orfeu.flushAudit().catch(() => undefined); // envia o resto da fila de auditoria
|
|
102
|
+
await apollo.server.stop().catch(() => undefined); // drain: fecha HTTP e WS
|
|
103
|
+
process.exit(0);
|
|
104
|
+
});
|
|
105
|
+
}
|
|
106
|
+
};
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
Pontos:
|
|
110
|
+
|
|
111
|
+
- O contexto HTTP só precisa de `{ App, req }`: os campos `orfeu*` (credencial, trace, routeId/clientId) são
|
|
112
|
+
preenchidos pelo `orfeuPlugin` no `didResolveOperation`. Não valide token no `context` — a validação é
|
|
113
|
+
por campo, no `secureResolvers`.
|
|
114
|
+
- `@orfeu/node` `^1.0.1` no `package.json` (a 1.0.0 aceitava `orfeuUser` forjado pelo `connectionParams`).
|
|
115
|
+
O contexto do WS (`ws-context.ts`, com a allowlist) está em [subscriptions.md](subscriptions.md).
|
|
116
|
+
|
|
117
|
+
### Orfeu fora do ar na subida: cair ou subir negando
|
|
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:
|
|
128
|
+
|
|
129
|
+
```ts
|
|
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
|
|
139
|
+
|
|
140
|
+
app.get('/health', (_req, res) => {
|
|
141
|
+
res.status(orfeuPronto ? 200 : 503).json({ ok: orfeuPronto, orfeu: orfeuPronto ? 'up' : 'connecting' });
|
|
142
|
+
});
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
O `secureResolvers` e o `assertSchemaSecured` continuam **antes** de qualquer tentativa (o catálogo precisa
|
|
146
|
+
estar registrado quando o `startup()` sincronizar).
|
|
147
|
+
|
|
148
|
+
- `compression()` antes do Apollo vale a pena quando há respostas grandes (JSON comprime 70–85%).
|
|
149
|
+
|
|
150
|
+
## `src/core/server/*.ts`
|
|
151
|
+
|
|
152
|
+
```ts
|
|
153
|
+
// http.server.ts
|
|
154
|
+
import http from 'node:http';
|
|
155
|
+
import type { Express } from 'express';
|
|
156
|
+
export class HttpServer {
|
|
157
|
+
public server: http.Server;
|
|
158
|
+
constructor(app: Express) { this.server = http.createServer(app); }
|
|
159
|
+
}
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
```ts
|
|
163
|
+
// ws.server.ts (graphql-ws 5: 'graphql-ws/lib/use/ws'; graphql-ws 6: 'graphql-ws/use/ws')
|
|
164
|
+
import { WebSocketServer } from 'ws';
|
|
165
|
+
import { useServer } from 'graphql-ws/lib/use/ws';
|
|
166
|
+
import type { GraphQLSchema } from 'graphql';
|
|
167
|
+
import type http from 'node:http';
|
|
168
|
+
|
|
169
|
+
export class WsServer {
|
|
170
|
+
public server: WebSocketServer;
|
|
171
|
+
public serverCleanup: ReturnType<typeof useServer>;
|
|
172
|
+
constructor(httpServer: http.Server, schema: GraphQLSchema, context: (ctx: any) => Promise<unknown>, path: string) {
|
|
173
|
+
this.server = new WebSocketServer({ server: httpServer, path });
|
|
174
|
+
// `as any`: sob NodeNext o @types/ws pode resolver duas vezes (import/require) e o TS vê dois tipos distintos
|
|
175
|
+
this.serverCleanup = useServer({ schema, context }, this.server as any);
|
|
176
|
+
}
|
|
177
|
+
}
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
```ts
|
|
181
|
+
// apollo.server.ts (Apollo Server 5)
|
|
182
|
+
import { ApolloServer as ApolloBase } from '@apollo/server';
|
|
183
|
+
import { ApolloServerPluginDrainHttpServer } from '@apollo/server/plugin/drainHttpServer';
|
|
184
|
+
import { orfeuPlugin } from '@orfeu/node/apollo';
|
|
185
|
+
import type { OrfeuClient } from '@orfeu/node';
|
|
186
|
+
import type { GraphQLSchema } from 'graphql';
|
|
187
|
+
import type http from 'node:http';
|
|
188
|
+
import type { GraphQLContext } from '../context/context.types.js';
|
|
189
|
+
|
|
190
|
+
export class ApolloServer {
|
|
191
|
+
public server: ApolloBase<GraphQLContext>;
|
|
192
|
+
constructor(schema: GraphQLSchema, httpServer: http.Server,
|
|
193
|
+
wsCleanup: { dispose: () => void | Promise<void> }, orfeu: OrfeuClient) {
|
|
194
|
+
this.server = new ApolloBase<GraphQLContext>({
|
|
195
|
+
schema,
|
|
196
|
+
allowBatchedHttpRequests: true, // o front usa HttpBatchLink
|
|
197
|
+
introspection: process.env.GRAPHQL_INTROSPECTION === 'true', // só para o codegen local
|
|
198
|
+
plugins: [
|
|
199
|
+
ApolloServerPluginDrainHttpServer({ httpServer }),
|
|
200
|
+
orfeuPlugin(orfeu),
|
|
201
|
+
{ async serverWillStart() { return { async drainServer() { await wsCleanup.dispose(); } }; } },
|
|
202
|
+
],
|
|
203
|
+
});
|
|
204
|
+
}
|
|
205
|
+
}
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
## Contexto tipado
|
|
209
|
+
|
|
210
|
+
```ts
|
|
211
|
+
// src/core/context/context.types.ts
|
|
212
|
+
import type { Request } from 'express';
|
|
213
|
+
import type { OrfeuContext } from '@orfeu/node/apollo';
|
|
214
|
+
import type { AppModules } from '../../web/config/index.types.js';
|
|
215
|
+
|
|
216
|
+
export type GraphQLContext = OrfeuContext & { App: AppModules; req?: Request };
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
- No HTTP `req` existe; no WS não (há `connectionParams`). Use `req?` ou um tipo separado para
|
|
220
|
+
subscriptions.
|
|
221
|
+
- O usuário validado fica em `ctx.orfeuUser` **depois** do guard do campo — não leia no `context()`.
|
|
222
|
+
- Evite o padrão antigo de montar `metadata = { token, user }` à mão no contexto validando o token com
|
|
223
|
+
`orfeu.validateToken`: duplica o trabalho do `secureResolvers` e diverge dele. Se o contexto realmente
|
|
224
|
+
precisa de um usuário validado por fora (sem credencial crua), ele entra por `trustUser(ctx, claims)`;
|
|
225
|
+
`ctx.orfeuUser = ...` gravado à mão responde 401 desde o `@orfeu/node` 1.0.1 (skill **orfeu**).
|
|
226
|
+
|
|
227
|
+
## `AppModules` (composição)
|
|
228
|
+
|
|
229
|
+
```ts
|
|
230
|
+
// src/web/config/index.ts
|
|
231
|
+
import { TagsModule } from '../tags/modules/index.js';
|
|
232
|
+
import { OrdersModule } from '../orders/modules/index.js';
|
|
233
|
+
import type { AppModules as IAppModules } from './index.types.js';
|
|
234
|
+
|
|
235
|
+
export class AppModules implements IAppModules {
|
|
236
|
+
constructor(public Tags: TagsModule, public Orders: OrdersModule) {}
|
|
237
|
+
static async start(settings: NodeJS.ProcessEnv): Promise<AppModules> {
|
|
238
|
+
return new AppModules(new TagsModule(settings), new OrdersModule(settings));
|
|
239
|
+
}
|
|
240
|
+
}
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
`index.types.ts` declara só a interface (`Tags: TagsModule; ...`) e existe para quebrar o ciclo de import
|
|
244
|
+
entre `context.types.ts` e os módulos. Um módulo por domínio, nome em PascalCase igual ao do domínio
|
|
245
|
+
(`ctx.App.Orders`).
|
|
246
|
+
|
|
247
|
+
## `ExtendedSchema` (composição do schema)
|
|
248
|
+
|
|
249
|
+
```ts
|
|
250
|
+
// src/web/config/schemas/schemas.extends.ts
|
|
251
|
+
import merge from 'lodash/merge.js';
|
|
252
|
+
import type { IResolvers } from '@graphql-tools/utils';
|
|
253
|
+
import { Level } from '@orfeu/node';
|
|
254
|
+
import { operation } from '@orfeu/node/apollo';
|
|
255
|
+
import { JSONScalar } from '../../../core/schema/scalars.js';
|
|
256
|
+
import { TAGS_SCHEMA, TAGS_RESOLVERS } from '../../tags/schemas/index.js';
|
|
257
|
+
import { ORDERS_SCHEMA, ORDERS_RESOLVERS } from '../../orders/schemas/index.js';
|
|
258
|
+
|
|
259
|
+
export class ExtendedSchema {
|
|
260
|
+
public typeDefs: string[] = [
|
|
261
|
+
`#graphql
|
|
262
|
+
extend type Query { _health: String! }
|
|
263
|
+
`,
|
|
264
|
+
...TAGS_SCHEMA,
|
|
265
|
+
...ORDERS_SCHEMA,
|
|
266
|
+
];
|
|
267
|
+
public resolvers: IResolvers = merge(
|
|
268
|
+
{ JSON: JSONScalar, Query: { _health: operation(Level.PUBLIC, () => 'ok') } },
|
|
269
|
+
TAGS_RESOLVERS,
|
|
270
|
+
ORDERS_RESOLVERS,
|
|
271
|
+
);
|
|
272
|
+
}
|
|
273
|
+
```
|
|
274
|
+
|
|
275
|
+
`BASE_SCHEMA` declara os tipos raiz vazios (`type Query`, `type Mutation`, `type Subscription`) e os
|
|
276
|
+
scalars. Se `Mutation` ou `Subscription` acabar sem nenhum campo, o schema não valida: remova o tipo raiz
|
|
277
|
+
vazio do `BASE_SCHEMA` ou adicione um campo real (evite campos `_noop` só para tapar).
|
|
278
|
+
|
|
279
|
+
## Rotas REST ao lado do GraphQL
|
|
280
|
+
|
|
281
|
+
Upload de arquivo e leitura de binário (imagem) **não** passam pelo Apollo (evita `graphql-upload`). Monte um
|
|
282
|
+
`express.Router()` na base do path (`/app/graphql` → `/app`), faça proxy em stream para o serviço de trás e
|
|
283
|
+
repasse os headers do Orfeu com uma função própria (não há `OrfeuContext` fora do Apollo):
|
|
284
|
+
|
|
285
|
+
```ts
|
|
286
|
+
import type { Request } from 'express';
|
|
287
|
+
import { ACCESS_TOKEN_HEADER, APP_TOKEN_HEADER, CLIENT_ID_HEADER, ROUTE_ID_HEADER, TRACEPARENT_HEADER } from '@orfeu/node';
|
|
288
|
+
|
|
289
|
+
export function passthroughHeaders(req: Request): Record<string, string> {
|
|
290
|
+
const out: Record<string, string> = {};
|
|
291
|
+
const get = (n: string) => { const v = req.headers[n]; return (Array.isArray(v) ? v[0] : v)?.trim() || undefined; };
|
|
292
|
+
for (const n of [ACCESS_TOKEN_HEADER, APP_TOKEN_HEADER]) { const v = get(n); if (v) { out[n] = v; break; } }
|
|
293
|
+
for (const n of [TRACEPARENT_HEADER, ROUTE_ID_HEADER, CLIENT_ID_HEADER]) { const v = get(n); if (v) out[n] = v; }
|
|
294
|
+
return out;
|
|
295
|
+
}
|
|
296
|
+
```
|
|
297
|
+
|
|
298
|
+
O `traceparent` vai sem span novo (o gateway não audita essas rotas). Detalhes de proxy/stream:
|
|
299
|
+
**express**.
|
|
@@ -0,0 +1,183 @@
|
|
|
1
|
+
# Schema, resolvers e módulos
|
|
2
|
+
|
|
3
|
+
## SDL-first, em TypeScript
|
|
4
|
+
|
|
5
|
+
- O schema é **SDL** (não code-first), escrito em template strings com o marcador `#graphql` (realce de
|
|
6
|
+
sintaxe e o GraphQL do VS Code reconhecem). Não há `.graphql` no servidor — os `.graphql` com as
|
|
7
|
+
**operações** ficam no front (ver **angular**).
|
|
8
|
+
- `makeExecutableSchema({ typeDefs, resolvers })` de `@graphql-tools/schema` junta tudo.
|
|
9
|
+
- Cada arquivo de recurso exporta `schema: string[]` e `resolvers`. Mantenha o `schema` como **array** (permite
|
|
10
|
+
`...spread` sem caso especial) e use `schema: string[] = []` quando não houver nada — não `[``]`.
|
|
11
|
+
|
|
12
|
+
## Organização por domínio
|
|
13
|
+
|
|
14
|
+
```
|
|
15
|
+
web/orders/
|
|
16
|
+
modules/index.ts OrdersModule (REST)
|
|
17
|
+
schemas/
|
|
18
|
+
order/queries.ts extend type Query { ... } + tipos de leitura + resolvers.Query
|
|
19
|
+
order/mutations.ts extend type Mutation { ... } + inputs + resolvers.Mutation
|
|
20
|
+
order/subscriptions.ts extend type Subscription { ... } + resolvers.Subscription
|
|
21
|
+
order/index.ts reexporta com nomes únicos
|
|
22
|
+
index.ts ORDERS_SCHEMA / ORDERS_RESOLVERS
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
```ts
|
|
26
|
+
// order/index.ts
|
|
27
|
+
export { schema as ORDER_QUERIES_SCHEMA, resolvers as ORDER_QUERIES_RESOLVERS } from './queries.js';
|
|
28
|
+
export { schema as ORDER_MUTATIONS_SCHEMA, resolvers as ORDER_MUTATIONS_RESOLVERS } from './mutations.js';
|
|
29
|
+
export { schema as ORDER_SUBSCRIPTIONS_SCHEMA, resolvers as ORDER_SUBSCRIPTIONS_RESOLVERS } from './subscriptions.js';
|
|
30
|
+
|
|
31
|
+
// schemas/index.ts
|
|
32
|
+
import merge from 'lodash/merge.js';
|
|
33
|
+
import * as O from './order/index.js';
|
|
34
|
+
export const ORDERS_SCHEMA = [...O.ORDER_QUERIES_SCHEMA, ...O.ORDER_MUTATIONS_SCHEMA, ...O.ORDER_SUBSCRIPTIONS_SCHEMA];
|
|
35
|
+
export const ORDERS_RESOLVERS = merge({}, O.ORDER_QUERIES_RESOLVERS, O.ORDER_MUTATIONS_RESOLVERS, O.ORDER_SUBSCRIPTIONS_RESOLVERS);
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
- `merge` **sempre com `{}` como primeiro argumento** — `merge(a, b)` muta `a`.
|
|
39
|
+
- Importe `lodash/merge.js` (ESM + NodeNext) ou `import pkg from 'lodash'; const { merge } = pkg;`. Não
|
|
40
|
+
`import { merge } from 'lodash'` (CommonJS sem export nomeado em ESM).
|
|
41
|
+
- Tipos compartilhados entre domínios (ex.: `Environment`, tipos de um inventário comum) vão num domínio
|
|
42
|
+
`shared/` que entra primeiro no `ExtendedSchema`. Tipos de outro domínio podem ser estendidos
|
|
43
|
+
(`extend type Pool { ... }`), mas isso cria acoplamento de ordem — prefira tipos próprios.
|
|
44
|
+
|
|
45
|
+
## Convenções de SDL
|
|
46
|
+
|
|
47
|
+
| Item | Convenção |
|
|
48
|
+
| --- | --- |
|
|
49
|
+
| Campo raiz | camelCase, verbo + recurso: `listOrders`, `getOrder`, `createOrder`, `updateOrder`, `deleteOrder`; subscription: `orderChanged` / `subscribeOrderX` |
|
|
50
|
+
| Remoção | começa com `delete`/`remove`/`destroy` (vira método `delete` no Orfeu) |
|
|
51
|
+
| Retorno de Query/Mutation | `<Nome>Response!` (não-nulo), gerado por `envelopeType` |
|
|
52
|
+
| `data` do envelope | **sempre anulável** (`data: Order`, `data: [Order!]`) — falha devolve `data: null` |
|
|
53
|
+
| Inputs | `input CreateOrderInput`, `input UpdateOrderInput` (campos opcionais no update) |
|
|
54
|
+
| Remoção sem retorno | `envelopeType('MutationResult', 'ID')` reaproveitado |
|
|
55
|
+
| Nomes de campo | os mesmos que o serviço de trás devolve (snake_case ou camelCase, o que vier) — o gateway não renomeia |
|
|
56
|
+
| Docs | string de descrição no SDL (`"..."` ou `"""..."""`) nos campos raiz; aparece no codegen |
|
|
57
|
+
|
|
58
|
+
Declare cada `envelopeType(...)` **uma vez** no schema inteiro (tipo duplicado quebra o `makeExecutableSchema`).
|
|
59
|
+
|
|
60
|
+
## Scalars
|
|
61
|
+
|
|
62
|
+
```ts
|
|
63
|
+
// core/schema/scalars.ts
|
|
64
|
+
import { GraphQLScalarType, Kind, type ValueNode } from 'graphql';
|
|
65
|
+
|
|
66
|
+
function parseLiteral(ast: ValueNode): unknown {
|
|
67
|
+
switch (ast.kind) {
|
|
68
|
+
case Kind.STRING: case Kind.BOOLEAN: return ast.value;
|
|
69
|
+
case Kind.INT: case Kind.FLOAT: return Number(ast.value);
|
|
70
|
+
case Kind.OBJECT: return Object.fromEntries(ast.fields.map((f) => [f.name.value, parseLiteral(f.value)]));
|
|
71
|
+
case Kind.LIST: return ast.values.map(parseLiteral);
|
|
72
|
+
default: return null;
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
export const JSONScalar = new GraphQLScalarType({
|
|
77
|
+
name: 'JSON',
|
|
78
|
+
description: 'Valor JSON arbitrário (payloads dinâmicos).',
|
|
79
|
+
serialize: (v) => v, parseValue: (v) => v, parseLiteral,
|
|
80
|
+
});
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
`scalar JSON` no `BASE_SCHEMA` + `JSON: JSONScalar` nos resolvers. Use `JSON` só para payload realmente
|
|
84
|
+
dinâmico — tipo explícito dá codegen útil no front. Datas trafegam como `String` ISO 8601.
|
|
85
|
+
|
|
86
|
+
## Resolvers
|
|
87
|
+
|
|
88
|
+
```ts
|
|
89
|
+
createOrder: operation(Level.PRIVATE, (_: unknown, { input }: { input: CreateOrderInput }, ctx: GraphQLContext) =>
|
|
90
|
+
forward(() => ctx.App.Orders.create(input, ctx))),
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
- Uma linha: `operation(nível, (parent, args, ctx) => forward(() => ctx.App.<Dominio>.<metodo>(..., ctx)))`.
|
|
94
|
+
- O resolver **traduz argumentos** (GraphQL camelCase → query string do serviço, omitindo vazios) e mais
|
|
95
|
+
nada. Sem `try/catch` próprio (o `forward` cuida), sem texto de mensagem, sem transformar `data`.
|
|
96
|
+
- Exceção aceitável: remodelar um payload que o serviço publica num formato que o GraphQL não expressa
|
|
97
|
+
(ex.: dicionário `{ chave: valor }` → lista `[{ key, value }]`), de preferência numa função pura testada.
|
|
98
|
+
- Tipar `args` e `ctx` (`GraphQLContext`). `any` em `ctx` esconde o erro de `ctx.App` ausente no WS.
|
|
99
|
+
- Resolver de campo de tipo (não raiz) não passa pelo Orfeu e não precisa de `operation()`; evite fazer
|
|
100
|
+
chamada remota nele (N+1) — peça o dado já montado ao serviço de trás.
|
|
101
|
+
|
|
102
|
+
## Módulos (clientes dos serviços de trás)
|
|
103
|
+
|
|
104
|
+
```ts
|
|
105
|
+
import axios, { type AxiosInstance } from 'axios';
|
|
106
|
+
import { orfeuHeaders, type OrfeuForwardSource } from '@orfeu/node';
|
|
107
|
+
|
|
108
|
+
export class OrdersModule {
|
|
109
|
+
private http: AxiosInstance;
|
|
110
|
+
constructor(settings: NodeJS.ProcessEnv) {
|
|
111
|
+
this.http = axios.create({ baseURL: settings.PLATFORM_SERVICE_URL, timeout: 30_000 });
|
|
112
|
+
}
|
|
113
|
+
async create(body: unknown, caller: OrfeuForwardSource) {
|
|
114
|
+
const { data } = await this.http.post('/orders', body, { headers: orfeuHeaders(caller) });
|
|
115
|
+
return data; // envelope do serviço
|
|
116
|
+
}
|
|
117
|
+
async remove(orderId: string, caller: OrfeuForwardSource) {
|
|
118
|
+
const { data } = await this.http.delete(`/orders/${encodeURIComponent(orderId)}`, { headers: orfeuHeaders(caller) });
|
|
119
|
+
return data;
|
|
120
|
+
}
|
|
121
|
+
}
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
- `axios.create` **no construtor** (depois do dotenv), `baseURL` de variável de ambiente.
|
|
125
|
+
- Último parâmetro sempre `caller: OrfeuForwardSource` — o próprio `ctx`. `orfeuHeaders(ctx)` envia a
|
|
126
|
+
credencial recebida (`x-access-token` → `x-app-token` → `x-api-token`), o `traceparent` com o span DESTE
|
|
127
|
+
salto e `x-route-id`/`x-client-id`. Sem isso o serviço de trás grava a ação como entrada nova e a auditoria
|
|
128
|
+
aparece partida em dois traces. Detalhes: **orfeu**.
|
|
129
|
+
- `encodeURIComponent` em id que vai no path.
|
|
130
|
+
- Um módulo pode agrupar vários sub-recursos do mesmo prefixo REST (uma classe com seções), desde que siga
|
|
131
|
+
o mesmo serviço de trás.
|
|
132
|
+
- Status de negócio que **não** é erro mas vem como 4xx (ex.: 422 com a lista de achados em `data`): aceite
|
|
133
|
+
com `validateStatus` só naquela chamada:
|
|
134
|
+
|
|
135
|
+
```ts
|
|
136
|
+
const { data } = await this.http.post(`/orders/${id}/publish`, {}, {
|
|
137
|
+
headers: orfeuHeaders(caller),
|
|
138
|
+
validateStatus: (s) => (s >= 200 && s < 300) || s === 422,
|
|
139
|
+
});
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
- **TLS**: não desligue a verificação (`rejectUnauthorized: false`) no agente HTTP. Se a CA é interna,
|
|
143
|
+
configure `NODE_EXTRA_CA_CERTS`. Proxy de saída só por variável de ambiente e só onde for necessário.
|
|
144
|
+
- Header de trace próprio (`x-trace-id` com `AsyncLocalStorage`) é legado: o trace é o `traceparent` do
|
|
145
|
+
Orfeu. Não crie um segundo mecanismo.
|
|
146
|
+
|
|
147
|
+
## Filtros
|
|
148
|
+
|
|
149
|
+
- Filtros como **argumentos opcionais** do campo (`listOrders(status: String, from: String, to: String)`) ou
|
|
150
|
+
um `input OrderFilters` quando passam de três ou quatro.
|
|
151
|
+
- O resolver/módulo monta `params` só com o que veio preenchido (`null`, `undefined` e `''` não vão).
|
|
152
|
+
- Renomeie para o nome do serviço no módulo (`from` → `from_` quando o Python reserva a palavra).
|
|
153
|
+
- Arrays em query string: o padrão do axios é `key[]=a&key[]=b`; FastAPI espera `key=a&key=b` — use
|
|
154
|
+
`paramsSerializer: { indexes: null }` no `axios.create`.
|
|
155
|
+
- Filtro de **escopo do usuário** (só os itens do time dele) é do serviço de trás, que lê o token — o
|
|
156
|
+
gateway não decide visibilidade.
|
|
157
|
+
|
|
158
|
+
## Paginação
|
|
159
|
+
|
|
160
|
+
Padrão offset/limit, envelope com página:
|
|
161
|
+
|
|
162
|
+
```graphql
|
|
163
|
+
extend type Query {
|
|
164
|
+
"Mais novos primeiro; a tela pede páginas até completar `total`."
|
|
165
|
+
listOrders(filters: OrderFilters, offset: Int, limit: Int): OrdersPageResponse!
|
|
166
|
+
}
|
|
167
|
+
type OrdersPage { items: [Order!]!, total: Int!, offset: Int! }
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
```ts
|
|
171
|
+
listOrders: operation(Level.PRIVATE, (_: unknown, { filters, offset, limit }: ListArgs, ctx: GraphQLContext) =>
|
|
172
|
+
forward(() => ctx.App.Orders.list(filters, offset ?? 0, limit ?? 50, ctx))),
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
Padrão no resolver (`offset ?? 0`, `limit ?? 50`); o teto do `limit` é imposto pelo serviço de trás. Listas
|
|
176
|
+
pequenas (cadastros) podem devolver tudo (`data: [Order!]`) sem página. Cursor não é usado hoje.
|
|
177
|
+
|
|
178
|
+
## Módulos fora do HTTP (subscriptions)
|
|
179
|
+
|
|
180
|
+
Se uma subscription precisa chamar o serviço de trás (ex.: buscar o escopo do usuário), o `ctx.App` precisa
|
|
181
|
+
existir no contexto do WS — passe `App` no `extra` do `orfeuWsContext` (ver
|
|
182
|
+
[estrutura-bootstrap.md](estrutura-bootstrap.md)). Instanciar o módulo à parte, de forma preguiçosa, também
|
|
183
|
+
funciona, mas duplica clientes.
|