6. Gledalac, prava i greške
Poglavlje 6

Gledalac, prava i greške

Ista aplikacija radi za svakog ko otvori grupu: za admina, za člana, za nečlana javne grupe i za gosta bez naloga. Ovo poglavlje pokazuje kako aplikacija sazna ko je gledalac i šta sme, kako izgledaju greške i koje limite drži server.

6.1. Ko gleda: getCurrentProfile

getCurrentProfile() postoji u oba API-ja i vraća profil gledaoca ili null za gosta. Ne vraća {ok}, nego sam profil.

PoljeZnačenje
id, username, profile_picture_urlko je gledalac i njegova slika
description, description_formatopis profila
sharing"unique" ili "shared": da li profil koristi jedan nalog ili ga deli više njih
adminda li je gledalac admin grupe
rolesimena uloga koje profil ima u grupi
inserted_at, updated_atkad je profil napravljen i menjan
// Ask once, at start; the promise is reused wherever the profile is needed.
const profile = window.potok.getCurrentProfile();

async function greet() {
  const me = await profile;
  console.log(me ? `Zdravo, ${me.username}` : 'Gost');
}

void greet();

6.2. Gde je aplikacija i šta gledalac sme: getGroup

window.potok.getGroup() vraća {ok: true, group}: grupu aplikacije, njenog roditelja i šta gledalac tu sme.

id, name, is_public, inherits_members, inherit_role_keys
Grupa, da li je javna i da li nasleđuje članove roditelja (svih ili, uz inherit_role_keys, samo nosilaca tih uloga).
parent
{id, name, is_public, uses_api} roditelja, ili null ako ga gledalac ne vidi.
can_manage_children, can_create_children
Gledalac sme da menja podgrupe (ima edit_group ovde), odnosno i da ih pravi (create_subgroups). Od njih zavise pozivi za podgrupe (poglavlje 11).
everyone_creates_subgroups
Svaki član može ručno da doda podgrupu, mimo aplikacije.
can_start_polls
openPollForm radi za ovog gledaoca (poglavlje 12).
signed_in
false za gosta: nekoga bez naloga, u javnoj grupi koja je opis otvorila gostima.

6.3. Prava

Napomena

Server proverava prava pri svakom pozivu, pa aplikacija ne mora da ih zna unapred. Ipak, dugme koje gledaocu neće raditi bolje je ne prikazati: getGroup i getConfig kažu šta sme pre nego što pokuša.

6.4. Gost samo čita

Javna grupa može da otvori opis i onima bez naloga, i tada aplikacija radi i za njih. Za gosta getCurrentProfile() vraća null, a getGroup() ima signed_in: false.

Od poziva rade samo oni koji čitaju: podgrupe, mapa, javna glasanja i javna pravila. Umesto dugmeta koje gostu ne radi pokaži „Prijavi se“ sa openLogin(): strana odlazi na potok-ovu prijavu, koja gosta vraća na istu grupu. Okvir sam ne može da napusti stranu. Bilo gde osim kod gosta openLogin vraća unavailable.

async function setupWriteButton(button: HTMLButtonElement) {
  const me = await window.potok.getCurrentProfile();
  if (me) {
    button.textContent = 'Dodaj';
    return;
  }

  button.textContent = 'Prijavi se';
  button.addEventListener('click', () => void window.potok.openLogin(), potok.eventListenerOptions);
}

const button = document.querySelector<HTMLButtonElement>('.app-add');
if (button) void setupWriteButton(button);

Postojeće grupe zadržavaju kopiju aplikacije sa kojom su napravljene: aplikacija koja je naučila da radi sa gostima stiže samo u grupe napravljene posle nje.

Dev mock

?viewer=guest u adresi dev servera glumi gosta: nema profila, getGroup() ima signed_in: false i nijedno pravo, a openLogin samo piše u konzolu (poglavlje 13).

6.5. Odgovor i greška

Neuspeo poziv vraća {ok: false, error, message?}. message postoji (preveden) samo kad grešku nađe provera na serveru. Neke greške nose još polja: reason (invalid_rules, invalid_process), current (conflict), collection i path (invalid_process), index (createChildren).

Ako stranica ne odgovori za 10 s, promise se odbija. To je jedini slučaj kad poziv baca izuzetak, pa važne pozive obavij u try/catch.

Opšti kodovi grešaka (kodovi kolekcija su u poglavlju 9, a procesa u poglavlju 10):

KodKada
not_a_memberpoziv traži članstvo u grupi
forbiddengledalac nema pravo (izmena opisa, podgrupe, gost)
rate_limitedpreviše upisa zaredom, ili zbirova u minuti
invalid_valuedata nije JSON objekat
invalid_descriptionopis koji server ne prima
invalid_grouppodgrupa sa neispravnim poljima (createChildren dodaje index)
invalid_placemesto koje createPlace ili openMap ne prima
invalid_emojitoggleGroupReaction sa nečim što nije jedan emoji
invalid_datefrom ili to nije ISO 8601 trenutak sa zonom
invalid_matchmatch nije objekat do 4 KB
invalid_aggregateloš ključ, putanja ili previše polja u aggregateValues
timeoutzbir je trajao preko 5 s, a pogled mape preko 4 s
not_foundnema te podgrupe ili grupe, ili je gledalac ne vidi
stale_apppoziv je stigao iz aplikacije koja više nije na ekranu (poglavlje 7)
unavailableopenLogin van strane gosta; showGroup iz onoga što je showGroup otvorio
cancelledgledalac je zatvorio birač u pickEmoji
too_largepreviše odjednom: vrednost, konfiguracija ili više od 100 podgrupa u createChildren
unknown_methodstranica ne zna taj poziv (npr. stariji potok)
previewokvir za pregled u formi za izmenu ne prima pozive
disconnectedstranica trenutno nema vezu sa serverom

Kodovi lične memorije (invalid_key, too_big, too_many_keys) su u poglavlju 8.

6.6. Limiti

ŠtaGranica
upisinajviše 30 zaredom; limit se obnavlja tokom 10 s. Upisom se broje i reakcije, lična memorija i previewDescription
strana vrednostilistValues: najviše 200, podrazumevano 50; kolekcija: najviše 100
sve vrednosti odjednomgetGroupDataValues() bez limit: do 5000
zbiroviaggregateValues i summarizeValues zajedno 120 u minuti po gledaocu; jedan zbir najviše 5 s
odgovor stranice10 s, pa se promise odbija
vrednost kolekcije, konfiguracijado 64 KB i 512 KB kao JSON (too_large)
lična memorija100 ključeva po osobi, vrednost do 16 KB
localStorage256 KB po aplikaciji
podgrupestrana do 50 (podrazumevano 20); createChildren do 100 odjednom
mapado 2000 mesta; pogled najviše 4 s
glasanja30 po pozivu
ostalo sa serverapogledi mape 300 u minuti; gost 600 poziva u minuti po adresi; nečlanovi 10 vrednosti u minuti i 20 fajlova na sat; fajlovi aplikacije do 1 GB; createPlace 20 mesta na sat po profilu

Kad aplikacija upisuje mnogo vrednosti zaredom (uvoz, popunjavanje), rate_limited nije greška korisnika: sačekaj i pokušaj ponovo.

import type { PotokData } from './potok';

const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));

async function insertWithRetry(data: PotokData, tries = 5) {
  for (let attempt = 1; ; attempt++) {
    const reply = await window.potok.insertValue(data);
    if (reply.ok || reply.error !== 'rate_limited' || attempt === tries) return reply;
    await sleep(1000 * attempt);   // the limit refills over 10 s
  }
}

void insertWithRetry({ text: 'zdravo' });
Dev mock

Dev mock nema drugih korisnika, limita upisa ni grešaka poput not_a_member i stale_app. Kod koji ih obrađuje proveravaš tek u potok-u, ili glumeći drugog gledaoca sa ?viewer=.