Il protocollo di rete durevole (sperimentale)

Sperimentale. Il wire può cambiare, o la funzionalità può essere rimossa, in una release minor successiva. Versioni e l'hello descrittivo illustra come vengono distribuite le modifiche.

Il wire durable è il modo in cui Collie comunica con un agente durable. Questa pagina lo illustra per chi crea un agente durable senza l'SDK o desidera comprendere le operazioni eseguite dall'SDK. Le regole esatte si trovano in WIRE.md; in caso di discrepanze tra questa pagina e tale file, fa fede WIRE.md. L'SDK durevole gestisce l'intero processo.

Cosa transita

Collie chiama e il durable agent ascolta; ogni scambio è una richiesta HTTP con un corpo JSON.

Il durable agent ascolta su un socket Unix privato, oppure dietro TLS a un URL (Trasporti). Collie ne effettua il polling: non ci sono push, WebSocket né stream. Ogni percorso inizia con /session/v1, che è un nome fisso e non la versione. Ogni chiamata eccetto la prima hello include la versione nell'header X-Collie-Session. Il corpo di una richiesta è un singolo oggetto JSON di massimo 64 KiB, e un corpo POST vuoto viene letto come {}.

Ogni errore è un corpo JSON con un code, come 409 stale o 404 no-such-pane. Qualsiasi altro percorso restituisce 404 not-found. Una risposta che supera il proprio limite non viene letta, e un POST la cui risposta viene interrotta ha un esito sconosciuto (ID delle richieste).

Hello ed epoch

hello indica l'identità del durable agent, mentre l'epoch indica a quale suo avvio Collie si sta rivolgendo.

Collie chiama prima hello senza l'header di versione, sceglie la versione più recente supportata da entrambe le parti e la invia in ogni chiamata successiva. Finché ready è false, ogni route tranne hello risponde 503 starting, e il telefono mostra il durable agent come in fase di avvio. Un durable agent imposta ready solo dopo che ogni conversazione è stata mostrata di nuovo e ogni ask aperta è stata ripresentata, così che un riavvio non mostri mai un layout a metà.

L'ETag dello snapshot è "<epoch>-<rev>". rev aumenta a ogni modifica visibile per un lettore, pertanto un 304 non costa quasi nulla al durable agent. Una nuova epoca indica a Collie che il durable agent è stato riavviato. Collie continua a mostrare i riquadri correnti finché non legge il nuovo snapshot. Legge quindi ciascun riquadro con il relativo cursore precedente e ottiene l'intera vista corrente del riquadro in una sola risposta.

Una lettura non riuscita dopo una andata a buon fine mantiene l'ultimo snapshot per quel polling. Due errori consecutivi mostrano il durable agent come irraggiungibile. Un percorso socket che non supera la verifica dei permessi di accesso è subito irraggiungibile.

Ask e risposte

Un'ask è una scheda con una domanda, ed è aperta dall'evento ask del durable agent fino al suo ask-closed.

Un tocco che arriva dopo la decisione riceve 409 decided con il primo esito, e nulla viene eseguito. La scheda indica quindi chi ha deciso per primo: "Deciso nel durable agent.", "Scaduto prima di una risposta.", o, dopo un altro tocco, "Già risposto. Questa scheda scomparirà al prossimo aggiornamento.". Un'ask che il durable agent non riconosce più restituisce 200 too-late. La scheda mostra quindi "Non preso in carico. La domanda potrebbe ricomparire a breve.", poiché dopo un riavvio il durable agent potrebbe ripresentarla con lo stesso id.

Una richiesta appartiene a uno dei quattro tipi: permission, choice, text o form. Ciascuna ha un proprio formato di risposta, elencato con il Domande dell'SDK.

ID delle richieste

Ogni azione dal telefono include un id di richiesta, quindi viene eseguita al massimo una volta.

Il telefono genera un id di richiesta per ogni intento, e Collie registra la propria ricevuta prima di inoltrare l'id. L'agente durevole conserva almeno gli ultimi 500 id della propria epoca. La ripetizione di un id completato riceve nuovamente la prima risposta con replayed: true e non esegue alcunché. Lo stesso id con un payload diverso riceve 409 request-id-reused.

Collie non ritenta mai un POST in modo autonomo. Un POST che va in timeout, perde la connessione o riceve un 5xx ha un esito sconosciuto. In caso di risposta, la scheda mostra "Non è certo che la risposta sia arrivata. Riprova la invia un'altra volta.", e Riprova invia lo stesso id di richiesta, così la memoria dell'agente durevole risponde alla ripetizione.

Un nuovo tentativo che trova la richiesta chiusa o il turno passato non può determinare se il primo tentativo sia andato a buon fine. Collie risponde quindi al telefono "forse applicata", la scheda mostra "Potrebbe essere già applicata. Verificare la chat.", e l'azione non viene mai inviata una terza volta.

Trasporti

Un agente durevole usa uno dei due trasporti: un socket privato sulla macchina di Collie, o TLS con un token.

I byte sono identici su entrambi: le route, i corpi, l'intestazione di versione, l'ETag e i codici di errore. Cambia soltanto chi ha il permesso di raggiungere l'agente durevole.

Ciascun timeout rappresenta un termine per l'intero scambio, dalla connessione all'ultimo byte. Su TLS ogni poll è una richiesta che l'host potrebbe fatturare, incluso un 304.

Limiti

Collie tronca o rifiuta qualsiasi elemento oltre questi limiti; pertanto, un durable agent che si mantiene al loro interno non perde nulla.

Una stringa che supera il proprio limite viene troncata, e i relativi caratteri invisibili e di controllo vengono rimossi. Un elenco che supera il proprio limite mantiene i primi elementi. Una pagina della cronologia che supera il proprio limite non viene letta affatto.

Versioni e l'hello descrittivo

Oggi esiste una sola versione di protocollo, 1, e Collie usa 1..1.

Al rilascio della versione 2, Collie accetterà la versione 1 per una minor release successiva, per poi rimuoverla nella minor release seguente. Un lettore ignora campi, tipi di evento, tipi di elemento o codici che non riconosce. Un campo aggiunto all'interno della versione 1, come expiresAt o decidedBy, è facoltativo. Un nuovo campo obbligatorio, un nuovo significato per un campo esistente o un campo rimosso richiedono una nuova versione.

Una richiesta di tipo sconosciuto al telefono viene mostrata come richiesta a cui non è possibile rispondere dal telefono, senza pulsanti.

Quando i due intervalli non coincidono, Collie non legge più nulla dall'agente durevole. Una volta per epoch dell'agente durevole invia un ulteriore hello, questa volta con la propria versione, affinché l'agente durevole possa registrare la mancata corrispondenza nei propri log. L'agente durevole risponde 409 incompatible con un refusal che specifica entrambi gli intervalli. Questo è il telling hello.

Collie scrive una riga nei log per ogni intervallo rifiutato, e collie doctor mostra entrambi gli intervalli. La schermata home dell'agente durevole sul telefono mostra la stessa frase, ad esempio "The durable agent speaks wire v2, this Collie speaks v1. Update Collie, or the agent's SDK." Aggiornare il componente meno recente.

Dove si trovano le regole esatte

WIRE.md è il contratto, con ogni forma, codice e regola.

Le decisioni sottostanti sono documentate nel repository: