fa3ba88f40
- Add per-collection row cap (default 10k, env EXPORT_ROW_CAP) via Prisma take on all findMany calls - Add total size cap (default 100MB, env EXPORT_SIZE_CAP_MB); throws PayloadTooLargeException (413) when exceeded - Convert response to Node.js Readable stream piped via NestJS StreamableFile to avoid large in-memory buffers - Export ExportUserDataResult interface (stream + truncated flag) from handler - Update controller to set Content-Type/Content-Disposition headers and return StreamableFile - Document EXPORT_ROW_CAP and EXPORT_SIZE_CAP_MB env vars in Swagger - Extend tests: row-cap assertion (take arg), size-cap 413 path, stream assertions Fixes GOO-223 (M-1 from GOO-200 audit). Co-Authored-By: Paperclip <noreply@paperclip.ing>
54 lines
2.3 KiB
Markdown
54 lines
2.3 KiB
Markdown
# @goodgo/contracts-events
|
|
|
|
Cross-runtime (Node + Python) event contracts for RFC-004's async messaging
|
|
backbone. See [GOO-95](/GOO/issues/GOO-95) for the RFC and
|
|
[GOO-172](/GOO/issues/GOO-172) for Phase 0.
|
|
|
|
## What lives here
|
|
|
|
- `src/envelope.ts` — `EventEnvelope<T>` TypeScript type + `EVENT_ENVELOPE_SCHEMA_VERSION`.
|
|
- `src/uuid-v7.ts` — pure-Node UUIDv7 generator (no runtime deps).
|
|
- `src/event-types.ts` — string-literal union of all known event types.
|
|
- `schemas/envelope.schema.json` — JSON Schema for the envelope itself.
|
|
- `schemas/<event-type>.schema.json` — JSON Schema for each event payload.
|
|
|
|
The `schemas/` directory is consumed by the Python AI services
|
|
(`libs/ai-services`) via `redis-py` consumers — JSON Schema is the single
|
|
source of truth across runtimes.
|
|
|
|
## Envelope shape
|
|
|
|
```ts
|
|
interface EventEnvelope<TPayload = unknown> {
|
|
schemaVersion: number; // bump when envelope itself changes
|
|
eventId: string; // UUIDv7 — time-ordered, idempotency key
|
|
eventType: string; // dotted: "payment.completed"
|
|
occurredAt: string; // ISO-8601 UTC
|
|
producer: string; // service name, e.g. "api"
|
|
traceId: string; // OpenTelemetry-compatible (32 hex chars or "00…")
|
|
payload: TPayload; // event-specific, validated by per-type schema
|
|
}
|
|
```
|
|
|
|
`schemaVersion` starts at `1`. Bump only when the **envelope** changes;
|
|
payload changes are versioned per event-type schema independently.
|
|
|
|
## First 3 schemas (Phase 0 deliverable)
|
|
|
|
| Event type | Trigger |
|
|
|----------------------|--------------------------------------------------|
|
|
| `payment.completed` | Payment moves to `succeeded` after gateway IPN |
|
|
| `listing.approved` | Moderation approves a listing |
|
|
| `kyc.verified` | KYC review marks a user verified |
|
|
|
|
Phase 1 (notifications cutover, [GOO-173](/GOO/issues/GOO-173)) will add
|
|
the rest of the production event surface.
|
|
|
|
## Adding a new event type
|
|
|
|
1. Pick a stable dotted name (`<aggregate>.<past-tense-verb>`).
|
|
2. Add a `schemas/<name>.schema.json` JSON Schema describing the payload.
|
|
3. Add the literal to `src/event-types.ts`.
|
|
4. (Optional) Re-export a typed payload alias from `src/index.ts`.
|
|
5. Land + dual-publish for at least one sprint before any consumer hard-fails on it.
|