first
This commit is contained in:
JiriUhlir
@@ -0,0 +1,132 @@
|
||||
# meta — overview
|
||||
|
||||
A stateless multi-tenant API proxy over the **Meta Marketing API**
|
||||
(Facebook / Instagram advertising), exposed as one FastAPI app at
|
||||
`/apps/meta`.
|
||||
|
||||
The structure deliberately mirrors the sibling `analytics` service
|
||||
(config→env, credentials→headers, client per upstream, routers, central
|
||||
exception handling, Swagger at `/docs`), so anyone who knows one knows the
|
||||
other.
|
||||
|
||||
## Why a separate app and not a module in `analytics`
|
||||
|
||||
- `analytics` is built around one shared Google OAuth mechanism (token minting
|
||||
from service-account keys, scopes, quota project). Meta shares none of it.
|
||||
- The Graph API needs a different client: form-encoded writes, `appsecret_proof`,
|
||||
cursor pagination, async report jobs.
|
||||
- This module serves both **Agents** and **csbot**, so it is versioned and
|
||||
deployed independently.
|
||||
- `analytics` is declared read-only. Campaign management (phase 2) lands here,
|
||||
where the write guard rails can be designed from the start.
|
||||
|
||||
## Design principles
|
||||
|
||||
- **Stateless / no stored secrets.** Credentials arrive per request in `X-`
|
||||
headers and are used only to call the upstream. Nothing is persisted; there
|
||||
is no token cache, because the caller always supplies a fresh token.
|
||||
- **Thin passthrough.** Graph request/response bodies are forwarded as-is, so
|
||||
callers keep the full upstream API surface. Only authentication, versioned URL
|
||||
building, pagination and error mapping are added.
|
||||
- **No silent failures.** Every error is logged (never the secret values) and
|
||||
surfaced as JSON. Upstream errors preserve the upstream status and body.
|
||||
- **Version is config, not code.** `META_API_VERSION` sets the default and
|
||||
`X-Meta-Api-Version` overrides it per request, so a Graph upgrade never needs
|
||||
a deploy here.
|
||||
|
||||
## Layout
|
||||
|
||||
```
|
||||
app/
|
||||
config.py env-driven config (base URL, version, caps, timeout) — no secrets
|
||||
logging_config.py get_logger(); secrets are never logged
|
||||
errors.py MissingCredentialsError, UpstreamError + handlers
|
||||
credentials.py X- header dependencies + appsecret_proof derivation
|
||||
clients/
|
||||
graph.py Graph client: auth, URL building, paging, error mapping,
|
||||
rate-limit header capture
|
||||
routers/
|
||||
infra.py /health, /version
|
||||
entities.py /ads/... ad accounts, campaigns, ad sets, ads, creatives
|
||||
insights.py /ads/insights/... sync + async reporting
|
||||
passthrough.py /graph/{path} generic read-only Graph GET
|
||||
main.py app, root_path, usage middleware, router + handler registration
|
||||
```
|
||||
|
||||
## Reverse proxy
|
||||
|
||||
`ROOT_PATH` (`/apps/meta`) is passed to FastAPI's `root_path`, so the OpenAPI
|
||||
`servers` entry and Swagger "Try it out" use the public prefix. Internal routes
|
||||
are unprefixed (Caddy `handle_path` strips the prefix).
|
||||
|
||||
## Authentication summary
|
||||
|
||||
| Header | Required | Behaviour |
|
||||
| --- | --- | --- |
|
||||
| `X-Meta-Access-Token` | one of these | Sent upstream as `Authorization: Bearer`. A Business Manager **System User** token is recommended. |
|
||||
| `Authorization: Bearer <token>` | one of these | Equivalent alternative; `X-Meta-Access-Token` wins if both are present. |
|
||||
| `X-Meta-App-Secret` | no, recommended | The proxy derives `appsecret_proof` (HMAC-SHA256 of the token) per request. Required when the app enforces app-secret proof. |
|
||||
| `X-Meta-Api-Version` | no | Per-request Graph version, e.g. `v25.0`. Validated as `vNN.N`, optionally restricted by `META_ALLOWED_API_VERSIONS`. |
|
||||
|
||||
The token goes upstream as a **header**, never as an `access_token` query
|
||||
param, so tokens do not end up in intermediate access logs.
|
||||
|
||||
## Configuration (environment variables)
|
||||
|
||||
| Variable | Default | Meaning |
|
||||
| --- | --- | --- |
|
||||
| `META_GRAPH_BASE_URL` | `https://graph.facebook.com` | Graph base URL. |
|
||||
| `META_API_VERSION` | `v25.0` | Default Graph version. |
|
||||
| `META_ALLOWED_API_VERSIONS` | *(empty)* | Optional comma-separated allowlist for `X-Meta-Api-Version`. Empty = any well-formed version. |
|
||||
| `META_MAX_PAGES` | `100` | Page cap for auto-paging. |
|
||||
| `META_ASYNC_POLL_INTERVAL_SECONDS` | `2` | Poll interval for async insights jobs. |
|
||||
| `META_ASYNC_MAX_WAIT_SECONDS` | `120` | Wait budget for `/run`. |
|
||||
| `HTTP_TIMEOUT_SECONDS` | `60` | Upstream request timeout. |
|
||||
| `LOG_LEVEL` | `INFO` | Log level. |
|
||||
|
||||
## Rate limits
|
||||
|
||||
Meta reports quota consumption in `X-App-Usage`, `X-Ad-Account-Usage` and
|
||||
`X-Business-Use-Case-Usage`. A middleware copies whatever the upstream returned
|
||||
onto our own response, so callers can pace themselves instead of discovering a
|
||||
throttle by being blocked.
|
||||
|
||||
## Pagination
|
||||
|
||||
List endpoints **follow `paging.next` by default** (`all_pages=true`) and return
|
||||
the complete list, so callers never have to implement a cursor loop:
|
||||
|
||||
```json
|
||||
{ "data": [...], "pages_read": 3, "truncated": false }
|
||||
```
|
||||
|
||||
`truncated: true` (plus a `next` URL and a logged warning) means the
|
||||
`META_MAX_PAGES` cap was hit — a partial result never masquerades as a complete
|
||||
one. Graph's own page size defaults to 25, so pass a larger `limit` to cover
|
||||
more rows in fewer round trips.
|
||||
|
||||
Pass `all_pages=false` for a single raw page with the upstream `paging.cursors`
|
||||
untouched, when you want to drive the cursor yourself.
|
||||
|
||||
## Deliberately not wired
|
||||
|
||||
- **All write operations (phase 2).** Creating or updating campaigns, ad sets
|
||||
and ads is intentionally absent. Every current endpoint issues a GET, so the
|
||||
service cannot spend money. Before writes are added, the agreed pattern is:
|
||||
status forced to `PAUSED` server-side (activation stays manual), an
|
||||
idempotency key so a retried request cannot create a duplicate campaign, and a
|
||||
budget ceiling enforced here as a backstop.
|
||||
- **Instagram organic / Pages content.** Reachable today through the read-only
|
||||
`/graph/{path}` passthrough; typed endpoints can follow if they get regular use.
|
||||
- **Header-credential encryption.** Same deferral as `analytics` / `idoklad` /
|
||||
`csob`: header values are plaintext over TLS for now.
|
||||
- **Automated tests.** There is no test suite yet (matching `analytics`).
|
||||
Verification is the manual checklist below. This is acceptable while the
|
||||
service is read-only; **it should not stay that way once writes land.**
|
||||
|
||||
## Verification checklist (per AGENTS.md)
|
||||
|
||||
- `/health` returns 200.
|
||||
- `/docs` loads; `/openapi.json` `servers` contains `/apps/meta`.
|
||||
- New endpoints appear in Swagger with their `X-` headers in "Try it out".
|
||||
- Secrets never appear in logs or source.
|
||||
Reference in New Issue
Block a user