Piattaforma e server

Ogni applicazione PocketContext gira su un unico binario Go, pocketcontext, che incorpora PocketBase per l’archiviazione SQLite, l’autenticazione e le modifiche REST dei record. PocketContext aggiunge un endpoint SQL in sola lettura, /api/context/query, così un assistente può unire e aggregare i dati direttamente. Le scritture passano comunque dall’API dei record, dove vengono eseguite le regole e gli hook dell’applicazione.

Un’applicazione è una cartella di regole che il server carica, non un secondo tipo di server. In produzione ogni applicazione è un processo proprio, un database proprio e un client Google proprio. Il file POCKETCONTEXT_VERSION in quella cartella è il commit del server con cui l’applicazione è stata verificata. Compilare un binario del server più recente non aggiorna le tabelle dell’applicazione.

flowchart TD
  migrations["pb_migrations — tabelle e regole"]
  hooks["pb_hooks — controlli aggiuntivi"]
  config["pocketcontext.json — cosa può vedere SQL"]
  skill["skill e CLI"]
  ui["pagine del browser"]
  pb["PocketBase — accesso, record, file"]
  sql["Lettore SQL — solo domande"]
  snap["copia filtrata — solo le righe di questa persona"]
  data["pb_data — il database su disco"]

  migrations --> pb
  hooks --> pb
  config --> sql
  skill --> sql
  skill --> pb
  ui --> pb
  pb --> data
  sql --> data
  sql --> snap
  snap --> data

Leggi con SQL, scrivi tramite l’API

sequenceDiagram
  participant A as Assistente
  participant R as /api/context/query
  participant W as /api/collections/.../records
  participant D as Database

  A->>R: un SELECT, con un token bearer
  R->>D: connessione in sola lettura
  D-->>A: colonne, righe, troncato?

  A->>W: POST o PATCH di un record
  W->>D: regole e hook di PocketBase
  D-->>A: record salvato

SQL accetta una sola istruzione. I join, le aggregazioni e le normali funzioni di SQLite sono consentiti. Scritture, modifiche dello schema, transazioni e PRAGMA vengono rifiutate. I limiti predefiniti sono 2 secondi, 500 righe e 1 MiB di risultati. Quando si raggiunge il limite di righe, la risposta include truncated: true, quindi la risposta è incompleta.

Il token bearer proviene dalla collection indicata in authCollection, spesso users o agents. Un token da superutente non aggira SQL.

Spazio di lavoro condiviso o una copia privata

L’applicazione decide quali righe un assistente può vedere. Il server non inventa quella politica.

flowchart TD
  login[Account con accesso effettuato]
  login --> mode{Come è configurata questa app}
  mode -->|spazio di lavoro condiviso| all[Ogni account può leggere le colonne configurate]
  mode -->|istantanee filtrate| copy[Una copia privata delle sole righe di questa persona]
  all --> query[La query SQL viene eseguita]
  copy --> query

TaskContext, DealContext, RaiseContext e LinkContext sono spazi di lavoro condivisi: i colleghi vedono le stesse righe. PeopleContext, AccountContext, WikiContext, NotifyContext e ChatContext filtrano, ognuno con la propria regola. Con le istantanee filtrate, ogni query viene eseguita su un database separato che contiene solo le righe che quell’account può vedere. La copia viene riusata finché il database reale non registra una modifica. Le politiche che dipendono dall’orologio non vengono riusate.

Ricerca, trace e i file su disco

Alcune applicazioni attivano POST /api/context/search. L’assistente invia un nome di indice e del testo, non SQL, e le tabelle full-text restano fuori dall’endpoint SQL. Le applicazioni che usano istantanee filtrate costruiscono un indice privato dalle righe di quella persona.

Il tracciamento è disattivato a meno che pocketcontext.json non lo richieda. Una richiesta completata può essere scritta come una riga JSON: route, stato, id utente, durata e passaggi con nome come prepare, execute e scan. La riga non include password, corpi delle richieste né risultati delle query. Il testo SQL è facoltativo e limitato, perché una query può contenere valori privati. Il server non invia quella riga a ObserveContext. È il client dell’applicazione a caricarla in seguito. Vedi Osservazione.

pb_data contiene il database e le credenziali e resta fuori da Git. Fanne un backup prima di un aggiornamento. PocketBase è ancora pre-1.0, quindi leggi le note di aggiornamento prima di cambiare versione. Un superutente può bloccare le scritture tramite l’API di manutenzione senza fermare il processo. Le letture continuano e le nuove modifiche attendono finché il blocco non viene rimosso. Un’applicazione deve adottare quel contratto prima di usarlo per una migrazione.

Gli installer per Linux (amd64 e arm64) e per macOS 15 o successivo su Apple Silicon sono nella guida del server.

Strumenti accanto al server