restate / v1.0.0

Zanesljivost by design

Kaj restate jamči, ko je shramba počasna, odpove ali manjka, in kako brati napake, ki jih javi.

Na tej strani

Jamstva Shranjevanja po vrsti Preizkusite Ko nalaganje ne uspe Shrani in zapri Shramba ni na voljo Preverjanje in migracija shranjenih podatkov Lastna shramba Omejitve in časovne omejitve Kode napak

Jamstva

To vedenje je del pogodbe 1.0 in ga pokrivajo testi paketa.

Okoliščina	Kaj naredi restate
`Več shranjevanj zapored`	Izvede jih po vrsti za vsak store; shranjevanje v vrsti zapiše najnovejšo vrednost.
`Zapis se ni naložil`	autoSave in skupna shranjevanja ga preskočijo z LOAD_FAILED; zamenja ga le izrecni save().
`Komponenta se med shranjevanjem odklopi`	Zahtevano shranjevanje se zaključi; poznejši zapisi v uničen store se prezrejo.
`Shramba ni na voljo`	Store deluje v pomnilniku, status().available je false, shranjevanja pa se zavrnejo.
`Vmesnik obvisi`	Operaciji poteče čas po operationTimeoutMs, poznejše delo pa počaka, da vmesnik konča.
`Preveč čakajočega dela`	Nove operacije se zavrnejo s QUEUE_FULL, namesto da bi rasle brez meje.

Operacije enega storea se nikoli ne prekrivajo. Shranjevanje, ki se začne, medtem ko drugo čaka, vzame najnovejšo vrednost, zato shranjevanje ob vsaki spremembi zapiše zadnje stanje brez polnjenja vrste.

useDraft.set('A');
const first = useDraft.save(); // writes "A"
useDraft.set('B');
const second = useDraft.save(); // waits in the queue
useDraft.set('C');
const third = useDraft.save(); // joins the waiting save

await Promise.all([first, second, third]); // ['A', 'C', 'C'] — two writes

Preizkusite

Upočasnite shrambo, naj zapisi ne uspejo ali shrambo povsem odstranite.

KrmilnikNi del kode primera. Vrednosti pridejo v primer kot props.

Zakasnitevlatency
Neuspešni zapisifailWrites
Shramba ni na voljounavailable

<Example
  latency={700}
  failWrites={false}
  unavailable={false}
/>

Pripravljanje primera …

Primeri v živo potrebujejo JavaScript. Kodo spodaj lahko preberete takšno, kot je.

App.jsx

import { useEffect, useState } from 'react';
import { persistedRestate } from '@kkwaenggwari/restate';
import { flakyStorage, settings } from './storage.js';
import './styles.css';

const useNote = persistedRestate('', { key: 'lab-note', storage: flakyStorage });

export default function Example({ latency = 700, failWrites = false, unavailable = false }) {
  useEffect(() => {
    Object.assign(settings, { latency, failWrites, unavailable });
  }, [latency, failWrites, unavailable]);

  const note = useNote();
  const { dirty, operation, pending, error } = useNote.useStatus();
  const [results, setResults] = useState([]);

  const save = () =>
    useNote.save().then(
      (value) => setResults((list) => [`Shranjeno: ${JSON.stringify(value)}`, ...list]),
      (reason) => setResults((list) => [`Ni uspelo: ${reason.code ?? reason.message}`, ...list]),
    );

  return (
    <main>
      <label>
        Opomba
        <input value={note} onChange={(event) => useNote.set(event.target.value)} />
      </label>
      <div className="actions">
        <button onClick={save}>Shrani</button>
        <button
          onClick={() => {
            save();
            save();
            save();
          }}
        >
          Shrani trikrat
        </button>
      </div>
      <dl className="status">
        <dt>dirty</dt>
        <dd className={dirty ? 'warn' : 'ok'}>{String(dirty)}</dd>
        <dt>operation</dt>
        <dd>{operation ?? '-'}</dd>
        <dt>pending</dt>
        <dd>{pending}</dd>
        <dt>error</dt>
        <dd className={error ? 'bad' : ''}>{error ? (error.code ?? error.message) : '-'}</dd>
      </dl>
      <h2>Rezultati</h2>
      <ol className="log">
        {results.length ? (
          results.map((result, index) => <li key={results.length - index}>{result}</li>)
        ) : (
          <li>-</li>
        )}
      </ol>
    </main>
  );
}

storage.js

// A storage adapter whose speed and failures you can change.
const records = new Map();
export const settings = { latency: 0, failWrites: false, unavailable: false };
const wait = () => new Promise((resolve) => setTimeout(resolve, settings.latency));

export const flakyStorage = {
  isAvailable: () => !settings.unavailable,
  async getItem(key) {
    await wait();
    return records.get(key) ?? null;
  },
  async setItem(key, value) {
    await wait();
    if (settings.failWrites) throw new Error('Disk je poln');
    records.set(key, value);
  },
  async removeItem(key) {
    await wait();
    records.delete(key);
  },
};

Ko nalaganje ne uspe

restateManager.ready se zavrne z BULK_OPERATION_FAILED in našteje vsak store, ki ni uspel. Dokler se ta zapis ne naloži, ga autoSave in saveAll ne zamenjata in javita LOAD_FAILED.

Poskusite znova z initialize(), da ohranite spremembe in jih shranite, pokličite restore(), da jih zavržete, ali save(), da zapis namerno prepišete.

try {
  await restateManager.ready;
} catch (error) {
  // BULK_OPERATION_FAILED: one entry per store that could not load.
  for (const { store, error: cause } of error.failures) {
    console.error(store.key, cause.code);
  }
}

Shrani in zapri

Shranjevanje, zahtevano pred odklopom, se vseeno zaključi, zato obravnavi »Shrani in zapri« ni treba čakati.

function Document({ onClose }) {
  const useDraft = useRestateScope((scope) => persistedRestate('', { scope, key: 'draft' }));

  const saveAndClose = () => {
    useDraft.save(); // finishes even after this component unmounts
    onClose();
  };
  // …
}

Shramba ni na voljo

Upodabljanje na strežniku in shramba, ki jo blokira brskalnik, nista napaki ob zagonu. Preverite available, da uporabnikom poveste, da spremembe ostajajo le v pomnilniku.

const { available } = useDraft.status();

if (!available) {
  // Server rendering or blocked browser storage: the store works in memory
  // and save() rejects with STORAGE_UNAVAILABLE.
  showNotice('Changes are kept until you close this tab.');
}

Preverjanje in migracija shranjenih podatkov

version, migrate in validate vas varujejo pred starimi ali poškodovanimi zapisi. validate se izvede pred shranjevanjem ter po obnovi ali migraciji.

import { persistedRestate } from '@kkwaenggwari/restate';

const useSettings = persistedRestate(
  { theme: 'system' },
  {
    key: 'settings',
    version: 2,
    migrate(value, from, to) {
      if (from === 1 && to === 2 && typeof value?.darkMode === 'boolean') {
        return { theme: value.darkMode ? 'dark' : 'light' };
      }
      throw new Error('Unsupported stored version');
    },
    validate: (value) => ['system', 'light', 'dark'].includes(value?.theme),
  },
);

Lastna shramba

Primeren je kateri koli objekt z getItem, setItem in removeItem. Metode lahko vrnejo vrednosti ali Promise; isAvailable ni obvezen.

import { persistedRestate } from '@kkwaenggwari/restate';

const sessionStorageAdapter = {
  isAvailable: () => typeof sessionStorage !== 'undefined',
  getItem: (key) => sessionStorage.getItem(key),
  setItem: (key, value) => sessionStorage.setItem(key, value),
  removeItem: (key) => sessionStorage.removeItem(key),
};

export const useFilters = persistedRestate(
  { query: '' },
  {
    key: 'filters',
    storage: sessionStorageAdapter,
  },
);

Omejitve in časovne omejitve

Nastavite, kako dolgo sme trajati operacija, koliko jih sme čakati in kako velika sme biti vrednost.

persistedRestate(value, {
  key: 'draft',
  operationTimeoutMs: 10_000, // default 30000
  maxPendingOperations: 64, // default 256
  maxStorageCharacters: 1_000_000,
});

Kode napak

Napake, ki jih ustvari restate, imajo name RestateError, code in pri shranjenih storejih key. Vmesniki za shrambo in vaši callbacki lahko zavrnejo z lastnimi napakami.

Koda	Pomen
`BULK_OPERATION_FAILED`	Skupni klic, kot je restateManager.ready ali saveAll, je imel napake; glejte error.failures.
`INDEXEDDB_ABORTED`	Transakcija IndexedDB je bila prekinjena.
`INDEXEDDB_BLOCKED`	Odpiranje zbirke podatkov je blokirala povezava v drugem zavihku.
`INDEXEDDB_CONNECTION_CLOSING`	Povezava z zbirko podatkov se je zapirala, ko se je zahteva začela.
`INDEXEDDB_OPEN_FAILED`	Zbirke podatkov ni bilo mogoče odpreti.
`INDEXEDDB_REQUEST_FAILED`	Zahteva IndexedDB ni uspela.
`INDEXEDDB_STORE_MISSING`	V že ustvarjeni zbirki podatkov manjka object store.
`INVALID_STORAGE_RECORD`	Shranjen zapis ni veljaven zapis restate.
`INVALID_STORED_VALUE`	Vrednost ni prestala validate.
`LIFECYCLE_LIMIT`	Updater se je vedno znova zaganjal in ustavljal.
`LOAD_FAILED`	Zapisa ni bilo mogoče naložiti, zato ga samodejno ali skupno shranjevanje ni zamenjalo.
`MMKV_UNAVAILABLE`	react-native-mmkv ni bilo mogoče naložiti.
`MULTIPLE_ERRORS`	V eni operaciji je odpovedalo več callbackov; glejte error.errors.
`NOTIFICATION_LIMIT`	Opazovalci so v zanki kar naprej načrtovali spremembe.
`OBSERVER_ERROR`	Poslušalec ali callback življenjskega cikla je vrgel napako.
`OPERATION_ABORTED`	Operacija s shrambo je bila preklicana.
`QUEUE_FULL`	Čakalo je več operacij, kot jih dovoljuje maxPendingOperations.
`REENTRANT_SETTER`	Updater stanja je med izvajanjem poskusil spremeniti isti store.
`SCOPE_DESTROYED`	Za ustvarjanje storejev je bil uporabljen uničen scope.
`SEQUENCE_EXHAUSTED`	Notranjemu zaporedju je zmanjkalo identifikatorjev.
`STORAGE_BLOCKED`	Prejšnji klic vmesnika se po izteku časa ali preklicu ni zaključil.
`STORAGE_TIMEOUT`	Operacija je trajala dlje od operationTimeoutMs.
`STORAGE_UNAVAILABLE`	Shrambe tukaj ni mogoče uporabiti; store še naprej deluje v pomnilniku.
`STORAGE_VALUE_TOO_LARGE`	Kodirana vrednost presega maxStorageCharacters.
`STORAGE_VERSION_MISMATCH`	Zapis ima drugo različico in nobena funkcija migrate je ne obravnava.
`STORE_DESTROYED`	Prišlo je do naročnine na uničen store ali pa je bil pozvan k uporabi shrambe.

Napisano za API restate 1.0