Documentazione · riferimento

La scheda app.json

Ogni app ha nella sua cartella un file app.json. Il motore lo legge a ogni avvio per sapere come trattare l'app. Dalla console del motore la modifica un Proprietario, nella scheda Configurazione dell'app.

01 /Un esempio

La scheda dell'app di esempio «Parts price list» (Listino ricambi), quella dello standard per gli agenti: un'app PocketBase con login, due ruoli e lo strumento di import. I nomi tecnici sono in inglese, come chiede lo standard; nome e descrizione sono quelli che vedono le persone.

{
  "id": "parts-pricelist",
  "name": "Parts price list",
  "description": "Prices of the spare parts in the warehouse, updated from the supplier's Excel or CSV file.",
  "kind": "pocketbase",
  "access": "login",
  "port": 8105,
  "version": "0.1.0",
  "owner": "Spare parts warehouse",
  "auth": {
    "collection": "users",
    "roleField": "role",
    "roles": ["manager", "storekeeper"],
    "defaultRole": "storekeeper"
  },
  "tools": ["import"]
}

Un'app statica, fatta solo di pagine e aperta a tutti, ha una scheda più corta:

{
  "id": "guida-officina",
  "name": "Guida dell'officina",
  "kind": "static",
  "access": "public",
  "port": 8106,
  "version": "0.1.0",
  "owner": "Officina"
}

02 /I campi

03 /I valori di kind

04 /La sezione auth

Serve alle app PocketBase con accesso login. Quando una persona entra dal portale, il motore crea o aggiorna dentro l'app un utente con la stessa email. Alla prima entrata gli scrive il livello base; poi il ruolo si gestisce dentro l'app (e dalla console, scheda «Accessi e ruoli»). La sezione auth dice al motore dove farlo.

Nell'app di esempio i ruoli sono due, manager (responsabile) e storekeeper (magazziniere), e il campo del ruolo si chiama role; chi entra la prima volta è storekeeper:

"auth": {
  "collection": "users",
  "roleField": "role",
  "roles": ["manager", "storekeeper"],
  "defaultRole": "storekeeper"
}

Il campo del ruolo lo crea una migrazione dell'app, con gli stessi valori di roles. Se in seguito si aggiunge un ruolo alla scheda, il motore lo aggiunge anche ai valori ammessi da quel campo; un ruolo tolto dalla scheda resta ammesso, così chi lo ha continua a entrare, ma la console non lo propone più.

Quando crei dalla console un'app PocketBase con login e ruoli, il motore scrive da solo la sezione auth e aggiunge il campo role agli utenti dell'app.

05 /Dove va il codice

apps\<id>\
├── app.json            la scheda
├── app.json.prima      la versione precedente, dopo una modifica dalla console
├── release\            il codice, sostituibile senza toccare i dati
│   ├── public\         pagine di un'app statica
│   ├── pb_public\      pagine di un'app PocketBase
│   ├── pb_hooks\       hook (JavaScript di PocketBase)
│   └── pb_migrations\  migrazioni dello schema
├── state\
│   └── pb_data\        i dati: non fanno parte del pacchetto
└── logs\               output del processo

Un'app statica ha solo app.json e release\public.

06 /Percorsi riservati del motore

Su ogni porta di app il motore risponde da sé ad alcuni percorsi. Il codice dell'app non deve usarli per altro.

Le chiamate da amministratore PocketBase sulle porte delle app (/api/collections/_superusers/…) vengono respinte: l'amministrazione passa dalla console del motore.

07 /Cosa controlla il motore

Il motore legge le schede all'avvio e quando un Proprietario preme «Rileggi cartelle». Una scheda non viene usata se:

• il file non è JSON valido;
• il file ha due chiavi uguali a meno delle maiuscole e delle minuscole (per esempio port e Port);
• kind non è uno dei tre valori ammessi;
• manca name;
• port non è compresa tra 1024 e 64000, oppure la porta pubblica o quella interna è già usata da un'altra app, dal motore o da un altro programma;
• defaultRole non è uno dei ruoli.

Per una cartella nuova valgono anche i controlli di «Nuova app»: identificativo da 3 a 32 caratteri, non riservato e non già usato da un'altra app. Se access ha un valore diverso da public e login, l'app si tratta con login.

Un'app già registrata non si spegne per una scheda sbagliata: resta com'era, con l'ultima scheda buona, e il motore lo segnala. Si disattiva solo se la sua cartella non c'è più. Gli avvisi compaiono nel messaggio di «Rileggi cartelle» e nello Storico del motore. Quando crei un'app dalla console il motore controlla anche il formato dei ruoli: lettere minuscole, numeri e trattino basso.

08 /Regole per chi costruisce un'app

Le regole complete, con gli esempi di codice e la lista dei controlli prima della consegna, sono nello standard per gli agenti. In breve:

• Niente indirizzi o porte scritti nel codice. Si usano percorsi relativi e, per tornare al portale, /__platform/portal.
• Il pacchetto contiene solo codice: niente pb_data, niente dati reali, niente account di prova.
• Lo schema dei dati cambia con le migrazioni, mai cancellando pb_data.
• I dati si proteggono con le regole lato server, cioè le API rules di PocketBase. Nascondere un pulsante non protegge niente.
• Gli utenti non devono poter modificare il proprio ruolo: lo blocca il motore. Il ruolo lo cambia l'amministratore dalla console (un Proprietario o un Admin che gestisce l'app) o, se l'app lo prevede, chi ha il ruolo più alto.
• Le app con login non hanno bisogno di una pagina di registrazione né di un pulsante «Esci»: entrata e uscita passano dal portale.