Istruzioni di applicazione

1) Obiettivi, limiti e principi

1. Dare un'interpretazione chiara del protocollo/speck.

2. Verificare la compatibilità in modo indipendente.

3. Fornire esempi di lavoro client/server/webhoop.

4. Riduzione dei costi di integrazione e implementazione.

• RI si concentra sulla correttezza comportamentale, non sulle prestazioni massime.
• Include un set minimo di impostazioni prod (TLS, Loging, Metriche, Tracking, Limitator).
• Non sostituisce l'implementazione commerciale/alimentare, ma imposta il livello inferiore di qualità.

• Spec-first: la verità è nelle specifiche (OpenAPI/AsyncAPI/Proto/JSON-Schema/IDL).
• Deterministic & Motable - Risposte riproduttive e ficsture.
• Docs-as-Code: tutti in VCS, una versione con codice e test di conformazione.
• Portability contenitori, Helm/compose, manifesti finiti.

2) Viste di applicazione

RI-Server: riferimento del server per specifiche (REST/gRPC/GraphQL/Streaming).
RI-Client/SDK: riferimento client (una o due piattaforme popolari) + esempi.
RI-Webhook Receiver: gestore di webhoop firmati (convalida firma, retrai).
RI-Adatters: adattatori per broker di messaggi/bus di eventi (Avro/Proto/JSON, Schema Registry).
RI-Data: set di dati di riferimento, profili di privacy, snapshot d'oro.

3) Architettura del repository RI

ri/
specs/        # OpenAPI/AsyncAPI/Proto/JSON-Schema server/       # эталонный сервер src/
config/
docker/
helm/
client/       # эталонный клиент/SDK + примеры js/ python/ go/
conformance/     # конформанс-раннер, тест-кейсы, золотые файлы cases/
fixtures/
golden/
samples/       # end-to-end сценарии, Postman/k6/Locust security/      # ключи тестовые, политики, пример подписи docs/        # руководство, ADR, runbook, FAQ ci/         # пайплайны, конфиги, матрица совместимости tools/        # генераторы, линтеры, проверяльщики схем

• A ogni rilascio del tag. Y.Z e manufatti (immagini, liste, SDK).
• Per ciascun alloggiamento, la somma e la firma (supply-chain).
• CHANGELOG contrassegnato con modifiche «frammentarie» (breaking).

4) Specchi, contratti e schemi

Trasporti: OpenAPI/REST, gRPC/Proto, GraphQL SDL, AsyncAPI.
Semantica: codici di errore, idampotenza, cursori/paginazione, retrai, deduplicazione.
Eventi: tipo/versione, «id», «occurred _ at _ utc», «partition _ key», invarianti dell'ordine.
Firme/sicurezza: etichette OIDC/JWT, firma webhoop (HMAC/EdDSA), rotazione delle chiavi.

5) Test di conformazione

• conformità a specchi (convalida degli schemi),
• invarianti comportamentali (idemotia, ordinamento, cursori, TTL, retry-policy),
• sicurezza (firme, scadenze, nonce/replay-protezione),
• aspetti temporali (UTC, RFC3339, DST),
• valigette negative e condizioni limitrofe.

I file oro (golden) sono risposte/eventi di riferimento stabili contro i quali si confrontano i risultati.

python def run_conformance(target_url, cases, golden_dir):
for case in cases:
req = build_request(case.input)
res = http_call(target_url, req)
assert match_status(res.status, case.expect.status)
assert match_headers(res.headers, case.expect.headers)
assert match_body(res.json, golden_dir / case.id, allow_extra_fields=True)
for invariant in case.invariants:
assert invariant.holds(res, case.context)

consumer/sdk-js 1.4server 1.6, 1.7server 2.0 consumer/sdk-go 0.9server 1.5–1.7   –
webhook-receiver 1.1events v1events v2 (deprecated fields removed)

6) Produzione minima (senza scarti)

Sicurezza: TLS by default, intestazioni di protezione, vincolo CORS, limitatori, anti-replay.
Osservabilità: logi (struttura + maschera del PD), metriche (p50/p95/p99, error rate), tracsing (correlazione «sollest _ id»).
Config: tutto attraverso variabili di ambiente e file, lo schema di configurazione viene convalidato.
Perf-base: impostazioni dei pool sane, budget timeout della catena, cache coalescing.
Stabilità: retrai con jitter, circuito breaker, backpressure.

7) CI/CD e manufatti

1. Lint/assemblaggio/test unit.

2. Validazione speck (OpenAPI/AsyncAPI/Proto-lint).

3. Generazione SDK/stub da speck.

4. Conformità ri-server contro cases e oro.

5. Assieme aspetto (SBOM, firma), pubblicato nel Registro di sistema.

6. Script E2E (docker-compose/kind/Helm).

7. Pubblicare il docu e gli esempi.

• immagini contenitori «ri-server», «ri-webhook»,
• pacchetti SDK (npm/pypi/go),
• File Helm/compose,
• zip con «file dorati» e conformation runner.

8) Semi, SDK e «how-to»

Mini-app su due vetri popolari (ad esempio, Node. js/Go) con passaggi: autenticazione, chiamata API, elaborazione degli errori retrai webhook.
How-to: Idempotent POST, paginazione cursore, firma webhook, trattamento 429/503.
k6/JMeter profili per «smoke-perf» (non carico, ma salute di base).

9) Versioning e evoluzione

SemVer - Alterazioni di → MAGGIORE Aggiungi senza astinenza MINOR Correzioni PATCH.
Piano di deprecazione: annunci in specchi, flag Fiech, periodo di confidance shadow, poi enforce.
Interoperabilità eventi: le consolle devono ignorare campi sconosciuti.

10) Sicurezza e privacy in RI

Chiavi di prova e segreti solo per lo stand; al porto, istruzioni di sostituzione.
Occultamento del PD nei reparti; profili di anonimato dei ficstur (PII) sintetico.
Regola di tempo di vita degli artefatti dell'ambiente demo (TTL, Auto-Purificazione).

11) Osservabilità e SLO per RI

SLI/SLO RI: p95 <250 ms sullo stand di riferimento, errore rate <0. 5%, degradazione corretta in caso di compromissione della dipendenza (nel seme).
Dashboard: latency/Throughput/Errors + Conformation.
Decection-logs per la firma di webhoop/controlli di token (cause di guasto tracciate).

12) Prestazioni: base «sufficiente»

Profili «wrk/hey/k6» su «caldo» e «freddo».
Posizione chiara: RI non è in competizione sulla RPS massima, ma deve resistere al target standard (ad esempio 500 RPS per t3. medium con p95 <200ms) è un punto di riferimento per gli integratori.

13) Manuale operativo (runbook)

Avvio locale: compose/' make up '.
K8s-deposito: valori Helm, segreti, ingress, HPA.
Rotazione chiavi firma webhoop (periodo dual-key).
Traplshuting: errori frequenti e le loro cause (401, 403, 429, 503), come leggere i loghi/roulotte.

14) Controllo e possesso

Owners è il proprietario alimentare dello speck + piattaforma (tecnica) + sicurezza.
Calendario delle release e finestra di negoziazione delle modifiche frammentarie.
RFC/ADR per modifiche significative ai protocolli.

15) Adattamento a lingue/piattaforme

Il minimo consigliato è un livello (JS/TS) e uno di sistema (Go/Java).
Tipo di mapping: come vengono visualizzate le date/formati in denaro/decimal/set di byte.
Suggerimenti per i retraes/timeout/pool di configurazione in ogni SDK.

16) Anti-pattern

RI = «scaricabarile senza test», senza conformità, senza utilità.
Lo speck vive separato dal codice e dai test.
La mancanza di file d'oro e di invarianti è un flaconcino e una discussione sul comportamento.
Dipendenza da frame - Riferimento rigido a una singola libreria/cloud senza contenitore.
Le chiavi sono nel repository.
Perf-mix invece di comportamento: cercare di misurare «chi è più veloce» anziché «chi è giusto».
Un binario/immagine gigante senza modularità e manufatti (SDK/charts/speck).

17) Assegno-foglia architetto

1. Speck è canonica e valida? (OpenAPI/Proto/AsyncAPI/JSON-Schema)

2. Ci sono RI-server e almeno un RI-client/SDK con esempi completi?
3. Connessioni runner, valigette, file d'oro, negativi e invarianti sono pronti?
4. CI/CD raccoglie immagini, SDK, sito, lancia conformance e e2e?
5. Protezione predefinita: TLS, firme, limitatori, occultamento del PD?
6. Osservabilità: loghi/metriche/roulotte, dashboard e SLO per RI?
7. Perf-base documentata e riproduttiva?
8. Versioning di SemVer, matrice di compatibilità, procedura di deprecazione?
9. Runbook e avvio locale/cluster in un clic?
10. Proprietari, calendario di rilascio, RFC/ADR-thread definiti?

18) Mini esempio: webhook (pseudocode)

python def verify_webhook(request, keys):
sig = request.headers["X-Signature"]
ts = int(request.headers["X-Timestamp"])
if abs(now_utc().epoch - ts) > 300: return 401 # replay window body = request.raw_body if not any(hmac_ok(body, ts, k, sig) for k in keys.active_and_previous()):
return 401 event = json.loads(body)
if seen(event["id"]): return 200 # idempotency handle(event)
mark_seen(event["id"])
return 200

La valigetta di prova verifica la finestra dell'ora, la correttezza della firma (chiave corrente e precedente), l'idampotenza per 'event. id ', negativi (firma rovinata, «ts» scaduto).

Conclusione

L'implementazione è il canone di comportamento del sistema: uno speck unico, confermato da codice, test e manufatti. Una buona RI accelera l'integrazione, elimina l'ambiguità dei protocolli, garantisce la compatibilità verificabile e definisce standard minimi di sicurezza, osservabilità e prestazioni. Rendendola parte dello scheletro di ingegneria - e i vostri prodotti, partner e ecosistemi si muoveranno in modo più rapido e affidabile.