Plik historii celów DurableQR v1

Ten prywatny plik historii nie jest mapą ani plikiem routingu resolvera. Nie zmienia formatu map file v1.

Pobranie i autoryzacja

GET /v1/export/history używa JWT panelu i zweryfikowanego sub. GET /v1/int/export/history używa klucza API, User-Agent i aktualnego uprawnienia api_access. Żadne parametry query, w tym format i cursor, nie są obsługiwane. Nie ma CSV, publicznego URL, przechowywanego ani cyklicznego zrzutu.

Odpowiedź sukcesu to surowy JSONL, bez obudowy JSON i bez base64.

NagłówekWartość
Content-Typeapplication/jsonl; charset=utf-8
Content-Dispositionattachment; filename="durableqr-history.jsonl"
X-History-File-SHA256suma SHA-256 dokładnych bajtów, małe cyfry hex
X-History-File-Recordsdziesiętna liczba linii danych bez deklaracji
Cache-Controlno-store

Origin panelu może odczytać te nagłówki. Klient może zapisać durableqr-history.jsonl.sha256: suma, dwie spacje, nazwa pliku i LF. Backend nie zapisuje sidecara. SHA-256 nie jest podpisem ani dowodem kompletności.

Kanoniczne bajty i pola

UTF-8 bez BOM; każda linia, także ostatnia, kończy się LF. Bez CR, pustych linii i dodatkowych spacji między tokenami JSON. Unicode i URL nie są normalizowane; obowiązuje escaping JSON. Pierwsza linia to dokładnie {"format":"durableqr-history-file","format_version":1}. Każdy zwykły rekord zawiera dokładnie osiem kluczy w tej kolejności:

KluczZnaczenie
stable_idDokładnie 10 znaków ASCII z alfabetu 0123456789ABCDEFGHJKMNPQRSTVWXYZ
versionLiczba całkowita JSON od 1 do 9007199254740991
urlDokładny zapisany URL http lub https, maksymalnie 2048 bajtów UTF-8
actorUUID aktora, małe cyfry hex
timestampDokładny zapisany czas; zwykły UTC ma YYYY-MM-DDTHH:MM:SS.mmmZ; billing zachowuje precyzję kanonicznego UTC datetime.isoformat() i +00:00
rolled_back_fromnull albo liczba całkowita od 1 do version minus 1
transferred_fromnull albo UUID nadawcy transferu, małe cyfry hex
sourcenull albo billing

Schemat URL nie rozróżnia wielkości liter ASCII i wymaga znaku po //; U+0000 do U+001F, backslash i znaki Python str.isspace() są zabronione. Brak rollbacku lub transferu to null, nie brak klucza.

Rekordy sortowane są po ASCII stable_id, następnie liczbowo po version. Wersje obejmują 1 do przypiętej wersji META bez dziur i duplikatów. Powtarzane URL nie są deduplikowane; wersja stanu, fallbacku lub transferu nie musi oznaczać zmiany URL. Nieznane dodatkowe atrybuty są pomijane.

Brakujący lub wadliwy rekord zastępuje marker, np. {"stable_id":"2222222222","version":2,"error":"malformed_record"}. Nie ujawnia on danych wadliwego rekordu i oznacza niekompletną historię. Licznik i suma obejmują marker. Puste konto zawiera tylko deklarację i końcowy LF, records=0.

Przykład

{"format":"durableqr-history-file","format_version":1}
{"stable_id":"2222222222","version":1,"url":"https://example.org/old","actor":"11111111-1111-1111-1111-111111111111","timestamp":"2026-11-02T12:00:00.000Z","rolled_back_from":null,"transferred_from":null,"source":null}
{"stable_id":"2222222222","version":2,"url":"https://example.org/new","actor":"11111111-1111-1111-1111-111111111111","timestamp":"2026-11-02T12:01:00.000Z","rolled_back_from":null,"transferred_from":null,"source":null}
{"stable_id":"2222222222","version":3,"url":"https://example.org/old","actor":"11111111-1111-1111-1111-111111111111","timestamp":"2026-11-02T12:02:00.000Z","rolled_back_from":1,"transferred_from":null,"source":null}

Własność i spójność

Eksport obejmuje kody obecnego właściciela we wszystkich sześciu stanach, w tym frozen i deleted. Nagrobki zachowują historyczne URL w tym prywatnym pliku. Odbiorca transferu widzi wcześniejszą historię i pseudonimowych aktorów; poprzedni właściciel traci dostęp po zmianie META, nawet przy opóźnionym indeksie. Pobranej kopii nie można wycofać.

GSI1 jest ostatecznie spójny: nowy kod lub przyjęty transfer może pojawić się dopiero w kolejnym eksporcie. Licznik i suma nie dowodzą kompletności. Silnie spójne META jest sprawdzane przed i po odczycie wersji; zmiana właściciela lub wersji daje 503 całego pliku. Nie ma atomowego snapshotu wielu kodów ani blokady transferu, a zmiana po ostatnim odczycie pozostaje możliwa. Eksport można później ponowić.

Limity i błędy

Eksport synchroniczny dopuszcza najwyżej 50 kluczy GSI1, 100 wersji łącznie, 1 MiB bajtów UTF-8 pliku i 4 MiB serializowanej koperty Lambda proxy. 413 nie jest pierwszą stroną i nie ma kontynuacji; szybkie ponawianie nie zmniejszy historii. Ograniczenia są best-effort globalne dla trasy, nie dla konta: panel 0.0033/s i integrator 0.0008/s, burst 1, niezależnie od eksportu mapy.

StatusZnaczenie
400Niedozwolone query albo brak User-Agent integratora
401Brak lub nieprawidłowa tożsamość JWT
403Odmowa klucza API lub api_access
413Przekroczono limit kluczy, wersji lub rozmiaru; brak pliku
429Throttle gateway lub DynamoDB
503Deadline, błąd SDK, wadliwy indeks lub META albo zmiana META

Odmowy aplikacji mają standardowy JSON message i Cache-Control: no-store; aplikacyjne 429 i 503 mają Retry-After. Błędy gateway podlegają kontraktowi gateway bez obietnicy nagłówków aplikacji. Odmowa nie zawiera fragmentów pliku ani nagłówków sumy lub liczby. Nie ma publicznego fallbacku w storage.

Plik mapy

example.jsonl · example.jsonl.sha256