Spec couche 4 — air-url (chargement d’URL haut niveau ≈ URLSession)

Spécification technique — Version 0.1 (proposition). Couche 4 « Frameworks applicatifs » — fondation (couche + nom ratifiés par ADR-084).

Cadrage. air-url vise la couverture fonctionnelle du client URL-loading d’Apple (URLSession, dans Foundation) sans copier l’API — surface en vocabulaire Air idiomatique (note api-reseau-strategie). Bâti au-dessus d’air-http (h1/h2/h3) et air-network. Maison, pur Rust, zéro-C, zéro unsafe. Commodité applicative, pas un protocole filaire.

Décisions RATIFIÉES (ADR-084).

• Couche 4 élargie — le périmètre de la couche 4 passe de « frameworks UI » à « frameworks développeur : UI + fondation ». air-url est une commodité de fondation (comme URLSession dans Foundation chez Apple), au-dessus d’air-http/ air-network (L2). Alternative (haut de couche 2) rejetée (mélange de registres).
• Nom air-url — descriptif, vocabulaire Air, jamais « URLSession ». Alternatives air-web/air-fetch révisables par le BDFL sans rouvrir la couche.

Position et méthode

air-url orchestre des requêtes HTTP(S) de haut niveau : sessions, tâches, cache, cookies, défis d’authentification, transferts en arrière-plan, WebSocket. Il compose air-http (le protocole) + air-network (connexion/path-awareness) ; il n’a pas de cœur sans-IO (ce n’est pas un protocole filaire — comme air-network, c’est un substrat, mais applicatif).

Périmètre fonctionnel (checklist URLSession, vocabulaire Air)

Inventaire — ~16 objets

Surface (~14) : AirUrlSession (+ AirUrlSessionConfig/Builder), AirUrlRequest, AirUrlResponse, AirDataTask, AirDownloadTask, AirUploadTask, AirWebSocketTask, AirBackgroundSession, AirCachePolicy, AirHttpCache, AirCookieStore, AirAuthChallenge, AirUrlError. Support (~2) : AirTaskState (enum Suspended/Running/Completed/Cancelled), AirRedirectPolicy.

#![allow(unused)]
fn main() {
impl AirUrlSession {
    pub fn new(config: Arc<AirUrlSessionConfig>) -> Self;         // config Arc, Send+Sync
    pub async fn data(&self, request: AirUrlRequest) -> Result<(AirUrlResponse, Bytes), AirUrlError>;
    pub fn download(&self, request: AirUrlRequest) -> AirDownloadTask;   // → fichier, reprenable
    pub fn upload(&self, request: AirUrlRequest, body: AirBodySource) -> AirUploadTask;
    pub async fn websocket(&self, request: AirUrlRequest) -> Result<AirWebSocketTask, AirUrlError>;
}
}

Dépendances

air-http (L2, HTTP/1-2-3 + WebSocket), air-network (L2, connexion/path-awareness), air-runtime (L1, async), air-filesystem (L1, download/cache sur disque), air-config (L1, cookies/cache persistants), air-base-core (L1). Zéro-C (la seule surface C possible = celle, déléguée, d’air-tls sous air-http).

Sécurité

• TLS par défaut (via air-http/air-tls) ; downgrade http:// explicite.
• Cookies sûrs : Secure/HttpOnly/SameSite respectés ; isolation par origine ; pas d’envoi cross-site par défaut.
• Cache correct (RFC 9111) : jamais de réutilisation d’une réponse non cachable / no-store ; revalidation ETag/Last-Modified.
• Cert pinning (hook AirAuthChallenge) ; redirections validées (pas de fuite de credentials cross-origin ; limite de sauts).
• Transferts en arrière-plan : persistés (air-config/air-filesystem), reprenables.

Stratégie de tests

• Couverture couche 4 (cible selon nature, > 90 % logique).
• Cache : conformité RFC 9111 (fraîcheur, revalidation, no-store) ; cookies : RFC 6265 (SameSite, expiration, domaine/chemin) ; redirections (limite, credential-stripping).
• Interop : vs serveurs réels via air-http (loopback nginx) ; reprise de download.

Récapitulatif & décisions

1. Commodité applicative (couche 4 élargie, à ratifier) — compose air-http, pas un protocole.
2. Couverture URLSession, vocabulaire Air — jamais de copie d’API ; nom à figer.
3. Sécurité par défaut : TLS, cookies sûrs, cache correct, pinning, redirections validées.
4. Async 1ʳᵉ classe ; session Arc Send/Sync, tâches indépendantes.

Travail à reprendre

• Couche + nom : ratifiés (ADR-084 — couche 4 fondation, nom air-url).
• Cache/cookies persistants (schéma air-config) ; politiques de retry/timeout ; ABI C différée.

Licence : MPL 2.0. Statut : spec air-url (couche 4, à confirmer) v0.1 — chargement d’URL haut niveau ≈ URLSession, sur air-http. Nom + couche à ratifier.