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.
| Polje | Značenje |
|---|---|
id, username, profile_picture_url | ko je gledalac i njegova slika |
description, description_format | opis profila |
sharing | "unique" ili "shared": da li profil koristi jedan nalog ili ga deli više njih |
admin | da li je gledalac admin grupe |
roles | imena uloga koje profil ima u grupi |
inserted_at, updated_at | kad 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, ilinullako ga gledalac ne vidi.can_manage_children,can_create_children- Gledalac sme da menja podgrupe (ima
edit_groupovde), 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_pollsopenPollFormradi za ovog gledaoca (poglavlje 12).signed_infalseza gosta: nekoga bez naloga, u javnoj grupi koja je opis otvorila gostima.
6.3. Prava
- Upis traži članstvo u grupi. Nečlan dobija
not_a_member. - Izmena opisa traži pravo na izmenu grupe. Bez njega
updateDescriptionvraćaforbidden. - U kolekcijama prava određuje pravilo: ko piše, ko čita sve, a ko samo svoje (
capsizgetConfig, poglavlje 9). - Ključeve uloga grupe daje
listRoles():"everyone","admin"i UUID svake posebne uloge (poglavlje 9).
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);
- Gost dobija:
getGroup,listSubgroups,openGroup,shareGroup,showGroup,listPollsigetPoll(javna glasanja, bez glasa),getMapConfig,listPlaces,listPlacesAt,placeShapes, agetConfigisummarizeValuesgde je pravilo javno. Sve ostalo vraćaforbiddenilinot_a_member. - Pozivi sa jedne adrese ulaze u limit od 600 u minuti. Strana gosta ništa ne sluša uživo.
- Lična memorija gosta ostaje u pregledaču (poglavlje 8).
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.
?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):
| Kod | Kada |
|---|---|
not_a_member | poziv traži članstvo u grupi |
forbidden | gledalac nema pravo (izmena opisa, podgrupe, gost) |
rate_limited | previše upisa zaredom, ili zbirova u minuti |
invalid_value | data nije JSON objekat |
invalid_description | opis koji server ne prima |
invalid_group | podgrupa sa neispravnim poljima (createChildren dodaje index) |
invalid_place | mesto koje createPlace ili openMap ne prima |
invalid_emoji | toggleGroupReaction sa nečim što nije jedan emoji |
invalid_date | from ili to nije ISO 8601 trenutak sa zonom |
invalid_match | match nije objekat do 4 KB |
invalid_aggregate | loš ključ, putanja ili previše polja u aggregateValues |
timeout | zbir je trajao preko 5 s, a pogled mape preko 4 s |
not_found | nema te podgrupe ili grupe, ili je gledalac ne vidi |
stale_app | poziv je stigao iz aplikacije koja više nije na ekranu (poglavlje 7) |
unavailable | openLogin van strane gosta; showGroup iz onoga što je showGroup otvorio |
cancelled | gledalac je zatvorio birač u pickEmoji |
too_large | previše odjednom: vrednost, konfiguracija ili više od 100 podgrupa u createChildren |
unknown_method | stranica ne zna taj poziv (npr. stariji potok) |
preview | okvir za pregled u formi za izmenu ne prima pozive |
disconnected | stranica trenutno nema vezu sa serverom |
Kodovi lične memorije (invalid_key, too_big, too_many_keys) su u poglavlju 8.
6.6. Limiti
| Šta | Granica |
|---|---|
| upisi | najviše 30 zaredom; limit se obnavlja tokom 10 s. Upisom se broje i reakcije, lična memorija i previewDescription |
| strana vrednosti | listValues: najviše 200, podrazumevano 50; kolekcija: najviše 100 |
| sve vrednosti odjednom | getGroupDataValues() bez limit: do 5000 |
| zbirovi | aggregateValues i summarizeValues zajedno 120 u minuti po gledaocu; jedan zbir najviše 5 s |
| odgovor stranice | 10 s, pa se promise odbija |
| vrednost kolekcije, konfiguracija | do 64 KB i 512 KB kao JSON (too_large) |
| lična memorija | 100 ključeva po osobi, vrednost do 16 KB |
localStorage | 256 KB po aplikaciji |
| podgrupe | strana do 50 (podrazumevano 20); createChildren do 100 odjednom |
| mapa | do 2000 mesta; pogled najviše 4 s |
| glasanja | 30 po pozivu |
| ostalo sa servera | pogledi 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 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=.