Aller au contenu principal

appcore-peer-rpc

Paquet publié

Stable 1.0.0 · MSRV Rust 1.89 · crates.io · docs.rs · code source

Guide et exemples maintenus par le crate​

Le dépôt Runtime maintient le guide détaillé, exemple débutant et exemple intermédiaire. Le wiki résume la frontière publique ; les détails d’API et d’exécution restent avec le code du crate.

Responsabilité : client peer authentifié, host HTTP, validation et replay protection.

Dépendances internes : core, distributed contracts, security et transport.

API principale : traits token issuer/authenticator/dispatcher et implémentations HashToken/static; nonce stores mémoire/fichier; config, validator et hashes ; retry/client config et trait transport ; transports pooled et standard one-shot ; HTTP state et host.

Utilisez PooledPeerRpcTransport pour réutiliser des connexions bornées par origine. StdPeerRpcTransport conserve le comportement V1 one-shot avec Connection: close. Les deux consomment l'allocation owned du body du DTO HTTP. Les bodies V1 non compressés et V2 exacts conservent le même Vec<u8> dans HttpRequest, sans clone intégral à la frontière du transport.

Le client V1 déplace un payload outbound owned dans une enveloppe conservée pendant les retries bornés. Chaque retry renouvelle toujours les champs temporels, le nonce, la liaison du token et l'encodage HTTP. Avec un payload de 4 Mio sur cinq processus release Apple M1, le p50 est resté à +0,08 %, le RSS de pic a baissé de 7,21 %, le delta RSS du workload de 9,02 % et le delta RSS retenu de 7,99 %.

À l'entrée, decode_peer_rpc_envelope_json applique le plafond encodé et désérialise le body V1 non compressé directement depuis les octets HTTP empruntés. Le Runtime déplace ensuite l'allocation du payload décodé vers CommandEnvelope. Un workload de 4 Mio sur cinq processus a réduit le p50 de 53,06 à 52,35 ms, le RSS de pic de 35,80 à 23,81 Mio et le delta RSS de workload de 39,52 %.

À utiliser uniquement si tenant, cluster, source, cible, protocole, expiry, nonce et intégrité sont établis. AllowPeerAuthenticator est réservé aux tests.

Le Debug des DTO peer request, response, outbound et HTTP expose les tailles et omet bytes opaques, credentials, valeurs nonce/idempotence et details d'erreur distante.

Le BoundedReplayStore local au processus valide chaque nonce avec une limite de 128 octets, borne entrées actives et octets retenus estimés et n'autorise jamais un plafond par défaut supérieur à 32 Mio. L'opérateur peut choisir un plafond plus strict et consulter octets courants, pic, maximum et rejets sans exposer les nonces.

Maturité : surface peer V1 stable.

Codec V2 borné​

PeerRpcChunkEncoder et PeerRpcChunkAssembler traitent un stream V2 explicitement sélectionné un chunk borné à la fois. Les limites par défaut sont 64 KiB décodés par chunk, 96 KiB encodés, 64 MiB agrégés et 1 024 chunks. Les octets encodés utilisent une chaîne JSON base64 canonique, jamais un tableau d'entiers. Séquence, taille décodée exacte, SHA-256 par chunk et total, deadline, annulation et quota après gzip échouent de manière fermée. Un commit échoué n'expose jamais le sink partiel comme complet. Les chunks identity déplacent la même allocation owned de la source à la frame puis à l'assembler, sans cloner les octets décodés à chaque frontière. Une sonde fixe sur stack sur tout le chunk évite le gzip spéculatif uniquement s'il semble déjà incompressible ; les chunks structurés compressibles utilisent toujours gzip.

PeerRpcStreamRegistry possède les sessions partielles sous des quotas exacts de sessions et d'octets décodés. Les chunks de requête utilisent des fichiers exclusifs dans un répertoire de spool existant réservé au propriétaire; seuls les commits vérifiés atteignent le dispatcher et les réponses utilisent des pulls explicites et bornés. Erreur, annulation, expiration et fin libèrent le fichier et la réservation. Le snapshot expose sessions, octets réservés, saturations et nettoyages. Unix valide le propriétaire effectif et les modes répertoire/fichier 0700/0600. Windows rejette les reparse points et tout allow ACE hors du SID propriétaire du processus courant. Les autres plateformes échouent fermées.

Activez les routes HTTP signées uniquement avec PeerRpcHttpHost::with_v2_stream_registry; le host par défaut reste V1-only. query_stream_v2 et command_stream_v2 lient chaque body JSON exact à un bearer token et déplacent request/response une frame à la fois. Le JSON canonique est sérialisé directement dans SHA-256 pour cette liaison, sans conserver un second body encodé complet à côté de la frame. Les dépendants réutilisent ce chemin byte-exact via json_payload_hash. L'admission open vérifie tenant, cluster, cible, trace, deadline, idempotence command et nonce replay borné. Les frames ambiguës ne sont pas répétées; l'annulation best effort est soutenue par le nettoyage autoritaire de la deadline.

JSON reste le défaut V2. Le framing binaire exige with_v2_binary_codec() sur le host et with_stream_codec_v2(PeerRpcStreamCodecV2::Binary) sur le client. Des paths query/command séparés exigent le media type Postcard exact et lient le token au body binaire exact. Les bodies binaires n'utilisent jamais gzip HTTP; bornes décodées, gzip optionnel du chunk et hashes d'intégrité restent inchangés. Un support binaire absent ou incompatible est terminal, sans fallback JSON.

Rejets V2 typés​

Le candidat appcore-peer-rpc 1.0.2-rc consomme PeerRpcWireErrorV2 depuis les endpoints explicites de appcore-distributed-contracts 1.0.2-rc. Le code fixe phase et retryability; le délai est borné à 300 secondes, la corrélation à 128 octets et le message expurgé contrôlé par le protocole à 256 octets. Le client rejette les métadonnées connues contradictoires. Un code inconnu abandonne message/hint distants et devient un unique résultat unknown, observable et terminal.

Les réponses V1 stables conservent leur JSON. Le client mappe uniquement les codes exacts du host vers PeerRpcError::RemoteRejected; seuls les rejets exacts endpoint/capacité replay entrent dans le retry borné existant. Aucune sous-chaîne ou message libre ne contrôle le retry. L'ambiguïté d'un ACK V2 interdit toujours le retry automatique d'une frame.

Mettez à jour ensemble et gardez V1 explicite

Mettez à jour caller et target avant de sélectionner l'endpoint V2. V1 stable reste supporté pour les deployments legacy et n'est jamais mis à niveau, converti ou désactivé automatiquement.

La certification release clean-source à 6f3bc38 mesure 25 % d'octets body en moins, un p99 codec réduit de 93 % et un buffer borné réduit de 14 % entre 64 Kio et 4 Mio. Le cas 1 Kio progresse de 38 %/65 %/18 %; le RSS maximal de la suite est 306 448 Kio. /v1/peer/* analyse uniquement V1 et n'infère jamais V2. Le codec binaire reste en développement sans preuve Linux/Windows.