Nicolas Cantu
940cf59178
- Add packages/smart-ide-upstreams (versioned dist) for resolveUpstream + listUpstreamKeys - Wire smart-ide-global-api and smart-ide-sso-gateway via file: dependency - Add systemd user unit templates and install-smart-ide-gateway-systemd-user.sh (SSO After/Requires global API) - Update docs and VERSION 0.0.3
58 lines
2.7 KiB
Markdown
58 lines
2.7 KiB
Markdown
# API — smart-ide-global-api
|
||
|
||
Écoute par défaut : **`127.0.0.1:37149`**. Configuration : `services/smart-ide-global-api/.env.example`, agrégat [config/services.local.env.example](../../config/services.local.env.example).
|
||
|
||
## Rôle
|
||
|
||
Agrégateur HTTP **interne** : reçoit les requêtes authentifiées par `Authorization: Bearer <GLOBAL_API_INTERNAL_TOKEN>` (fourni par `smart-ide-sso-gateway`), relaie vers chaque micro-service avec son **jeton technique** et propage les en-têtes `X-OIDC-Sub` / `X-OIDC-Email` lorsqu’ils sont présents.
|
||
|
||
Les navigateurs et applications utilisateur ne doivent **pas** appeler ce port directement : passer par la **passerelle SSO** (`/proxy/<clé>/...`).
|
||
|
||
## Authentification
|
||
|
||
| Route | Auth |
|
||
|-------|------|
|
||
| `GET /health` | Aucune |
|
||
| Toutes les autres | `Authorization: Bearer` égal à `GLOBAL_API_INTERNAL_TOKEN` |
|
||
|
||
## Endpoints
|
||
|
||
### `GET /health`
|
||
|
||
Réponse `200` : `{ "status": "ok", "service": "smart-ide-global-api" }`.
|
||
|
||
### `GET /v1/upstreams`
|
||
|
||
Liste les clés d’amont : `{ "upstreams": [ "orchestrator", ... ] }` (même liste que côté SSO).
|
||
|
||
### Proxy — `ANY /v1/upstream/<upstream_key>/<path>`
|
||
|
||
- **`<upstream_key>`** : `orchestrator`, `repos_devtools`, `ia_dev_gateway`, `anythingllm_devtools`, `tools_bridge`, `langextract`, `regex_search`, `claw_proxy`, `local_office`.
|
||
- **`<path>`** : transmis à l’URL de base du service (ex. `/v1/upstream/orchestrator/v1/...` → `http://127.0.0.1:37145/v1/...`).
|
||
- **Corps** : relayé (limite `GLOBAL_API_MAX_BODY_BYTES`, défaut 32 MiB).
|
||
- **Erreurs** : `401` si Bearer interne absent ou incorrect ; `404` si clé inconnue ; `503` si `local_office` sans `LOCAL_OFFICE_API_KEY`.
|
||
|
||
## Journaux
|
||
|
||
Fichier **`.logs/global-api/access.log`** : lignes JSON (`ts`, `method`, `path`, `upstream`, `status`, `durationMs`, `oidcSub` si présent).
|
||
|
||
## Variables d’environnement
|
||
|
||
| Variable | Rôle |
|
||
|----------|------|
|
||
| `GLOBAL_API_HOST` / `GLOBAL_API_PORT` | Bind HTTP |
|
||
| `GLOBAL_API_INTERNAL_TOKEN` | Obligatoire — secret partagé avec la passerelle SSO |
|
||
| `GLOBAL_API_MAX_BODY_BYTES` | Taille max du corps |
|
||
| `SMART_IDE_MONOREPO_ROOT` | Racine monorepo pour `.logs/` (sinon déduction depuis le module) |
|
||
|
||
Jetons et hôtes des micro-services : mêmes noms que dans `config/services.local.env.example`.
|
||
|
||
## Source des amonts
|
||
|
||
Les clés et la résolution `host:port` / jetons sont définies dans le paquet partagé **`packages/smart-ide-upstreams/`** (`@4nk/smart-ide-upstreams`). Toute nouvelle clé d’amont doit y être ajoutée une seule fois, puis `npm run build` dans ce paquet et commit du répertoire `dist/`.
|
||
|
||
## Voir aussi
|
||
|
||
- [sso-gateway-api.md](./sso-gateway-api.md)
|
||
- [sso-gateway-service.md](../features/sso-gateway-service.md)
|