NeboAI
NeboAI
להתחלה

App Sidecar

sidecar הוא קובץ בינארי שרץ לצד אפליקציה. הוא מגיש את ה-API של הדף, שומר את הנתונים של האפליקציה ונותן כלים לעובד של האפליקציה. Nebo מפעיל אותו, מנתב אליו בקשות דרך socket מקומי ומפעיל אותו מחדש כשהוא נכשל.

החוזה

sidecar הוא שרת gRPC על Unix socket. האזן בנתיב שב-NEBO_APP_SOCK וממש את apps.v0.UIService. Nebo קורא ל-HandleRequest עבור כל בקשה; HealthCheck ו-Configure הם חלק מהשירות אבל כרגע לא נקראים. ה-socket חייב להופיע בתוך ה-startup_timeout של המניפסט, שברירת המחדל שלו היא 10 שניות והמקסימום 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 רצים ב-macOS וב-Linux.

איפה Nebo מוצא את הקובץ הבינארי

בתיקיית האפליקציה, Nebo משתמש בראשון מבין אלה שקיים:

  1. קובץ בשם binary
  2. קובץ בשם app
  3. הקובץ הראשון ב-tmp/
  4. הקובץ הראשון ב-bin/
  5. קובץ ההפעלה הראשון ב-sidecar/target/release/, לפיתוח מקומי

הקובץ הבינארי חייב להיות קובץ רגיל וניתן להפעלה, לא קישור סימבולי, ובגודל של עד 500 MB. אפליקציות שפורסמו נושאות אותו ב-bin/<name>. כשהקובץ משתנה בדיסק, Nebo מפעיל מחדש את ה-sidecar.

סביבה

ה-sidecar מתחיל עם סביבה ריקה ועם המשתנים האלה:

משתנהערך
NEBO_APP_ID, NEBO_APP_NAME, NEBO_APP_VERSIONהזהות של האפליקציה.
NEBO_APP_DIRתיקיית האפליקציה.
NEBO_APP_SOCKה-socket להאזנה, <app folder>/<id>.sock. Nebo מגדיר את ההרשאות שלו ל-0600.
NEBO_DATA_DIRתיקיית הנתונים של האפליקציה, <data>/appdata/agents/<id>/. זו גם תיקיית העבודה.
NEBO_API_URLה-API המקומי של הבוט, http://127.0.0.1:<port>.
NEBO_APP_TOKENאסימון לקריאה ל-API של האפליקציות בבוט.
PATH, HOME, TMPDIR, LANG, LC_ALL, TZמועבר כמו שהוא.

הפלט הסטנדרטי והשגיאה הסטנדרטית נכתבים ל-sidecar.log בתיקיית הנתונים. הקלט הסטנדרטי הוא pipe; סוף קובץ פירושו ש-Nebo כבר לא שם, וה-sidecar צריך לצאת. ה-sidecar רץ בקבוצת תהליכים משלו.

בקשות מהדף

בקשה ל-/apps/<id>/api/<path>, שהדף שולח עם neboFetch ונתיב יחסי, מגיעה ל-HandleRequest כש-path מוגדר ל-<path>. נתיבים שמתחילים ב-_ נדחים. גוף הבקשה מוגבל ל-10 MB והתשובות ל-32 MB.

כלים לעובד

הצהר על כלים ב-agent.json של האפליקציה. כל אחד הופך לכלי בשם app__<app>__<name>, שנטען כשהעובד צריך אותו. קריאה הופכת לבקשה ל-sidecar לפי method ו-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" } } }
  }
]

קריאה ל-Nebo

ה-sidecar יכול להשתמש באותם שירותים כמו הדף על ידי קריאה ל-$NEBO_API_URL/api/v1/apps/$NEBO_APP_ID/... עם הכותרת Authorization: Bearer $NEBO_APP_TOKEN.

נתיבמה עושה
GET /storage, GET|PUT|DELETE /storage/<key>מאגר המפתח-ערך של האפליקציה.
POST /agents/invoke, POST /agents/streamשואל עובד: {message, agent, data}. תשובות בזרימה הן server-sent events.
POST /janus/complete, POST /janus/streamקריאה ישירה למודל: {messages, model, temperature, max_tokens, system}.
POST /http/proxyבקשה חיצונית, {url, method, headers, body}, שמותרת לפי הרשאות ה-network: של האפליקציה.
GET /identityהעובד של האפליקציה.

מחזור חיים

  • Nebo בודק את ה-socket כל שלוש שניות.
  • sidecar שנכשל מופעל מחדש אחרי שנייה אחת, וההמתנה מוכפלת עד 60 שניות לכל היותר. אחרי חמישה כישלונות ברציפות הוא מסומן ככושל. sidecar שנשאר פעיל 60 שניות נחשב תקין שוב.
  • בקשה ל-sidecar שנעצר מפעילה אותו וממתינה עד 15 שניות. בקשות GET ו-HEAD נשלחות שוב.
  • כדי לעצור sidecar, Nebo שולח SIGTERM לקבוצת התהליכים שלו, ואחרי שתי שניות הורג אותו.