PT

Données des comptes d'application : clés et objets

Toute application publiée sur jumphp.net qui donne un compte à ses utilisateurs (pseudo + mot de passe) peut aussi garder leurs données sur le serveur, pour les retrouver sur le PC, le téléphone et le navigateur, sans écrire de serveur à soi. Deux façons, au choix ou ensemble :

  • un magasin clé-valeur : des clés (settings, save/slot1, score:2026-11…) qui valent du JSON ou du texte, chacune avec sa version, et une recherche de clés par préfixe ou par motif (score:2026-*) ;
  • des objets entiers : les octets d'un objet sérialisé (serialize() de PHP, igbinary, JSON, MessagePack…) envoyés tels quels, versionnés : le serveur garde les dernières versions, on relit n'importe laquelle.

Le serveur ne lit jamais ces données : il ne désérialise rien, il garde des octets. Chaque compte ne voit que les siennes, et une application ne voit jamais celles d'une autre (ada sur deux applications = deux comptes). Supprimer le compte (DELETE /me) efface tout tout de suite ; un compte inutilisé 18 mois est supprimé avec ses données.

En PHP avec JumPHP, la classe JumPHP\Platform\AppAccount fait tout cela pour vous, sans jamais bloquer (plus bas).

L'API

Base : https://jumphp.net/api/apps/<slug>/account (la même que la connexion), avec le jeton de l'appareil : Authorization: Bearer wzd_…. CORS ouvert, aucun cookie, réponses jamais mises en cache (Cache-Control: no-store).

Requête Ce qu'elle fait
GET /storage ce que le compte utilise et ses limites : {usage: {keys, kvBytes, objects, versions, objectsBytes}, limits}
GET /kv/<clé> {key, type, value, version, size, updatedAt, device} + ETag: "<version>" (If-None-Match → 304)
PUT /kv/<clé> le corps est la valeur : Content-Type: application/json (du JSON) ou text/plain (du texte UTF-8) → 201 (nouvelle) ou 200 {key, type, version, size, updatedAt}
DELETE /kv/<clé> supprime la clé → {deleted}
GET /kv liste et recherche : prefix, match, limit, cursor, values=1 → {items: [...], next}
GET /kv?keys=a,b,c lecture groupée (100 clés au plus) : {items: [... avec value], missing: [...]}
PUT /objects/<nom> une nouvelle version : le corps est l'objet (ses octets) ; ?format=php-serialize, ?keep=10, ?encoding=base64, ?sha256=…, ?type=… → 201 / 200
GET /objects/<nom> les octets de la dernière version (application/octet-stream) ; ?version=N une version gardée ; ?encoding=base64 en JSON
GET /objects/<nom>/versions l'historique : {name, latest, keep, versions: [{version, size, sha256, format, contentType, createdAt, device}]} (la plus récente d'abord)
GET /objects les objets : prefix, limit, cursor → {items: [{name, version, size, sha256, format, contentType, updatedAt, device, keep, versions}], next}
DELETE /objects/<nom> supprime l'objet et toutes ses versions → {deleted}

device est l'identifiant de l'appareil qui a écrit (celui de GET /me), updatedAt / createdAt des dates ISO 8601.

Les clés

Une clé : 1 à 128 caractères parmi A-Z a-z 0-9 . _ : / -, commençant par une lettre ou un chiffre. Les majuscules comptent (Save et save sont deux clés). Les / et : servent à ranger : save/slot1, prefs:audio. Les clés sont triées octet par octet.

Une valeur : du JSON (Content-Type: application/json : un objet, un tableau, un nombre, une chaîne, true, null) ou du texte (text/plain, UTF-8, sans octet nul). 64 Ko au plus. Pour des octets quelconques, utilisez un objet. GET rend la valeur décodée dans value (un objet JSON vide reste {}).

T='Authorization: Bearer wzd_…'
B=https://jumphp.net/api/apps/mon-app/account
curl -X PUT -H "$T" -H 'Content-Type: application/json' -d '{"volume":0.8,"theme":"dark"}' $B/kv/settings
# → 201 {"key":"settings","type":"json","version":1,"size":29,"updatedAt":"2026-11-20T10:00:00+00:00"}
curl -H "$T" $B/kv/settings
# → {"key":"settings","type":"json","value":{"volume":0.8,"theme":"dark"},"version":1,"size":29,...}
curl -X PUT -H "$T" -H 'Content-Type: text/plain' --data-binary 'acheter du pain' $B/kv/notes/courses

Chercher des clés

GET /kv donne les clés dans l'ordre, sans les valeurs (sauf values=1), 100 par page (limit jusqu'à 1 000, 100 avec les valeurs) :

Paramètre
prefix les clés qui commencent par ce texte, tel quel (save/, save_ : le _ n'est pas un joker)
match un motif sur toute la clé : * = n'importe quoi (même rien), ? = un caractère. score:2026-*, save/slot?, *:audio
limit combien de clés par page
cursor la page suivante : la valeur de next de la réponse précédente (null : c'était la dernière)
values 1 : les valeurs avec
keys à la place des autres : ces clés-là exactement, séparées par des virgules (100 au plus), valeurs comprises
curl -H "$T" "$B/kv?prefix=score:&match=*-12&values=1"
# → {"items":[{"key":"score:2026-12","type":"json","version":3,"size":4,"updatedAt":"…","device":"a1b2c3d4e5f6","value":1200}],"next":null}
curl -H "$T" "$B/kv?keys=settings,save/slot1,inconnue"
# → {"items":[{…settings…},{…save/slot1…}],"missing":["inconnue"]}

Versions et If-Match

Chaque clé et chaque objet a une version qui monte de 1 à chaque écriture (ETag: "3"). Pour qu'un appareil n'efface jamais sans le savoir ce qu'un autre vient d'écrire, il écrit en disant la version qu'il a lue :

  • If-Match: "3" : l'écriture ne passe que si la version est encore 3 ; sinon 412 {code: "version_conflict", current: {…}} avec la version actuelle (la valeur comprise pour une clé) : l'appareil fusionne et renvoie avec la nouvelle version ;
  • If-Match: "0" : seulement si la clé (l'objet) n'existe pas encore ;
  • sans If-Match : l'écriture passe toujours (la dernière gagne) ; pratique pour un réglage que seul un appareil change.

DELETE accepte aussi If-Match.

Les objets entiers (PHP serialize(), igbinary, JSON…)

PUT /objects/<nom> garde les octets du corps tels quels et en fait une nouvelle version. Le nom : 1 à 128 caractères parmi A-Z a-z 0-9 . _ : - (pas de /). Paramètres :

format ce que sont ces octets, pour vous : php-serialize, igbinary, json, msgpack… (1 à 32 de a-z 0-9 . + _ -, raw par défaut). Le serveur le garde et le rend, sans s'en servir
keep combien de versions garder, de 1 à 50 (10 par défaut ; gardé pour les écritures suivantes). Les plus anciennes au-delà sont effacées
encoding=base64 le corps est le base64 des octets (pour un client qui n'envoie que du texte)
sha256 l'empreinte des octets : refusé (400) si ce qui arrive ne l'a pas (un envoi coupé en route)
type le type MIME à garder (sinon le Content-Type de la requête, sinon application/octet-stream)

La réponse : {name, version, size, sha256, format, contentType, createdAt, device, keep, versions} (201 pour la première version).

GET /objects/<nom> rend les octets de la dernière version, toujours en application/octet-stream (avec X-Content-Type-Options: nosniff : un navigateur ne les exécute jamais), et leurs métadonnées dans les en-têtes ETag, X-Object-Version, X-Object-Latest, X-Object-Format, X-Object-Content-Type, X-Object-Sha256. Avec ?encoding=base64 : du JSON {name, version, latest, size, sha256, format, contentType, createdAt, device, encoding: "base64", data}. ?version=N relit une version gardée (404 version_not_found si elle n'est plus gardée) : pour revenir en arrière, relisez-la puis écrivez-la de nouveau (elle devient la dernière, l'historique reste).

curl -X PUT -H "$T" --data-binary @partie.ser "$B/objects/partie?format=php-serialize&keep=5"
curl -H "$T" "$B/objects/partie/versions"
curl -H "$T" -o ancienne.ser "$B/objects/partie?version=2"

Désérialiser sans danger : unserialize() de PHP sur des octets venus du réseau peut créer n'importe quel objet et lancer son code (__wakeup, __destruct). Donnez toujours la liste des classes permises : unserialize($octets, ['allowed_classes' => [Partie::class, Joueur::class]]) (jamais sans allowed_classes), ou préférez du JSON. Le serveur, lui, ne désérialise jamais rien.

Limites et erreurs

Par compte
Valeur d'une clé 64 Ko
Clés 2 000, 4 Mo de valeurs en tout
Objet (une version) 2 Mo
Objets 200, 32 Mo en tout avec leurs versions gardées
Versions gardées 10 par défaut, de 1 à 50 par objet (keep)
Liste 1 000 clés par page, 100 avec les valeurs ; lecture groupée : 100 clés
Écritures 600 par 10 minutes, 200 Mo écrits par jour
Requêtes d'un appareil 300 par minute (avec celles du compte)

Ces données sont celles de votre application (réglages, sauvegardes, progression, listes) : pas des fichiers. Un morceau de musique, une vidéo ou une image lourde ne tiennent pas dans 2 Mo, et n'ont rien à faire là.

Erreurs, en JSON {error, code} : 400 bad_request (paramètre, JSON invalide, base64, empreinte) / bad_key (clé ou nom refusé), 401 unauthorized / revoked (se connecter de nouveau), 404 not_found (clé, objet) / version_not_found (version plus gardée), 412 version_conflict (avec current), 413 too_big (valeur ou objet trop gros) / quota (le compte est plein, avec usage), 415 unsupported_type (ni JSON ni texte) ou texte qui n'est pas de l'UTF-8, 429 rate_limited (avec Retry-After et retryAfter).

Depuis PHP (JumPHP)

JumPHP\Platform\AppAccount est le client de toute cette API (connexion comprise) pour une application JumPHP, sur le bureau, dans le navigateur et sur Android. Il ne bloque jamais : chaque appel rend une Task dont la réponse arrive à une image suivante. Il garde le jeton de l'appareil dans var/ de l'application.

use JumPHP\Platform\AppAccount;

$account = AppAccount::for($this->engine, 'mon-app');          // https://jumphp.net/api/apps/mon-app/account
$account->signIn($pseudo, $motDePasse)->then(fn () => $this->status = 'connecté', fn (\Throwable $e) => $this->error = $e->getMessage());

// clé-valeur
$account->set('settings', ['volume' => 0.8]);
$account->get('settings')->then(fn (?array $item) => $this->volume = $item['value']['volume'] ?? 1.0);
$account->search(prefix: 'score:', match: '*-12', values: true)->then(fn (array $page) => $this->scores = $page['items']);

// un objet PHP entier, versionné
$account->store('partie', $this->partie)->then(fn (array $v) => $this->version = $v['version']);
$account->load('partie', [Partie::class, Joueur::class])->then(fn (?Partie $p) => $this->partie = $p ?? new Partie());
$account->versions('partie')->then(fn (array $h) => $this->historique = $h['versions']);

La documentation complète de la classe est dans le dépôt de JumPHP : docs/platform-account.md.

Pour le propriétaire de l'application

Avec le serveur MCP du playground, votre Claude voit les comptes de vos applications (jamais celles des autres, ni celles d'un projet qu'on vous a seulement partagé) : app_accounts_stats (combien de comptes, actifs, ce que pèsent leurs données), list_app_accounts (les pseudos, leur dernière visite, leurs clés et objets : jamais un mot de passe ni un jeton), get_app_account_data (les clés et objets d'un compte, les valeurs seulement si on les demande : pour déboguer) et delete_app_account (supprime un compte et tout ce qu'il garde, avec confirm: true). Ces données sont celles de vos utilisateurs : n'en lisez que ce qu'il faut.