Kontrakten
En sidecar er en gRPC-server på en Unix-socket. Lyt på stien i NEBO_APP_SOCK, og implementér apps.v0.UIService. Nebo kalder HandleRequest for hver anmodning; HealthCheck og Configure er en del af tjenesten, men kaldes ikke i dag. Socketten skal dukke op inden for manifestets startup_timeout, som er 10 sekunder som standard og højst må være 120.
syntax = "proto3";
package apps.v0;
service UIService {
rpc HealthCheck(HealthCheckRequest) returns (HealthCheckResponse);
rpc Configure(SettingsMap) returns (Empty);
rpc HandleRequest(HttpRequest) returns (HttpResponse);
}
message HttpRequest {
string method = 1; // GET, POST, PUT, DELETE, ...
string path = 2; // relative to /apps/{id}/api/
string query = 3; // raw query string
map<string, string> headers = 4;
bytes body = 5;
}
message HttpResponse {
int32 status_code = 1;
map<string, string> headers = 2;
bytes body = 3;
} Sidecars kører på macOS og Linux.
Hvor Nebo finder binæren
I appens mappe bruger Nebo den første af disse, der findes:
- En fil med navnet
binary - En fil med navnet
app - Den første fil i
tmp/ - Den første fil i
bin/ - Det første program i
sidecar/target/release/, til lokal udvikling
Binæren skal være en almindelig, eksekverbar fil, ikke et symbolsk link, og højst 500 MB. Udgivne apps har den i bin/<name>. Når filen ændres på disken, genstarter Nebo sidecaren.
Miljø
Sidecaren starter med et tomt miljø og disse variabler:
| Variabel | Værdi |
|---|---|
NEBO_APP_ID, NEBO_APP_NAME, NEBO_APP_VERSION | Appens identitet. |
NEBO_APP_DIR | Appens mappe. |
NEBO_APP_SOCK | Socketten, der skal lyttes på, <app folder>/<id>.sock. Nebo sætter dens tilstand til 0600. |
NEBO_DATA_DIR | Appens datamappe, <data>/appdata/agents/<id>/. Også arbejdsmappen. |
NEBO_API_URL | Bottens lokale API, http://127.0.0.1:<port>. |
NEBO_APP_TOKEN | Et token til at kalde bottens app-API. |
PATH, HOME, TMPDIR, LANG, LC_ALL, TZ | Videregives. |
Standardoutput og standardfejl går til sidecar.log i datamappen. Standardinput er en pipe; slut på filen betyder, at Nebo er væk, og at sidecaren skal afslutte. Sidecaren kører i sin egen procesgruppe.
Anmodninger fra siden
En anmodning til /apps/<id>/api/<path>, som siden laver med neboFetch og en relativ sti, når HandleRequest med path sat til <path>. Stier, der starter med _, afvises. Anmodningers brødtekst er begrænset til 10 MB og svar til 32 MB.
Værktøjer til medarbejderen
Erklær værktøjer i appens agent.json. Hvert bliver et værktøj med navnet app__<app>__<name>, der indlæses, når medarbejderen har brug for det. Et kald bliver til en anmodning til sidecaren på method og path.
"tools": [
{
"name": "list_deals",
"description": "List open deals, optionally filtered by stage.",
"method": "GET",
"path": "/deals",
"input_schema": { "type": "object", "properties": { "stage": { "type": "string" } } }
}
] Kald Nebo
Sidecaren kan bruge de samme tjenester som siden ved at kalde $NEBO_API_URL/api/v1/apps/$NEBO_APP_ID/... med headeren Authorization: Bearer $NEBO_APP_TOKEN.
| Rute | Gør |
|---|---|
GET /storage, GET|PUT|DELETE /storage/<key> | Appens nøgle-værdi-lager. |
POST /agents/invoke, POST /agents/stream | Spørger en medarbejder: {message, agent, data}. Streamede svar er server-sent events. |
POST /janus/complete, POST /janus/stream | Et direkte modelkald: {messages, model, temperature, max_tokens, system}. |
POST /http/proxy | En udgående anmodning, {url, method, headers, body}, tilladt af appens network:-tilladelser. |
GET /identity | Appens medarbejder. |
Livscyklus
- Nebo tjekker socketten hvert tredje sekund.
- En fejlet sidecar genstarter efter et sekund, fordoblet op til højst 60 sekunder. Efter fem fejl i træk markeres den som fejlet. En sidecar, der holder sig kørende i 60 sekunder, er sund igen.
- En anmodning til en stoppet sidecar starter den og venter op til 15 sekunder. GET- og HEAD-anmodninger prøves igen.
- For at stoppe en sidecar sender Nebo SIGTERM til dens procesgruppe og dræber den derefter efter to sekunder.