FAQ
Limits, retention windows, self-hosting versus the hosted API, and where to file an engine bug versus a hosting bug.
Limits
How many resources and cells can I have?
Every tenant's pool is resident in one shared process, so the ceiling is a service-wide budget, not a per-tenant quota: 100,000 registered resources and 500,000 reputation cells summed across all tenants by default. That is deliberate — a single active tenant may use the entire budget alone, and several tenants share it dynamically as they show up. A fixed per-tenant cap would throttle a lone tenant while nothing else was competing.
The budget is only checked by calls that would grow durable state: a Register for a resource the pool has not seen, or a Report for a (resource, context) pair that has no cell yet. Those are refused with RESOURCE_EXHAUSTED. Everything else — acquiring, reporting on existing cells, reading — keeps working. It is a fail-safe ceiling, not a fail-closed gate.
Are there request rate limits?
Not on the data plane today — no per-tenant RPC quota. The one limiter that exists is on POST /api/auth/login, keyed by source IP: five failed attempts in fifteen minutes block that IP for fifteen minutes (429 with Retry-After), plus a global per-second backstop. Read endpoints instead clamp their own inputs: score-history?hours= to [1, 720] and events?limit= to [1, 500], so no single call can trigger an unbounded scan.
How many contexts should one resource have?
As many as you have things that can burn it independently — typically one per destination. Each distinct (resource, context) pair is one cell against the budget above, so a context derived per-request (a request id, a timestamp) will both exhaust the budget and produce cells with no useful history. See Concepts.
Retention
| Data | Kept for | Notes |
|---|---|---|
| Reputation state (cells, blocklist, registrations) | Indefinitely | Live state, checkpointed to PostgreSQL and restored on restart. Not a time series. |
Score samples (score-history) | 7 days | Sampled once a minute per live cell; older samples are purged hourly. |
Audit events (GET /api/events) | Indefinitely by default | Age-based purging is opt-in and off unless configured, so the trail is complete unless you asked for a window. |
| Usage meters | Not purged | Daily rows. GET /api/usage returns the last 30 days plus the current month's total. |
| Leases | Until TTL or release | Runtime coordination only — not part of the durable snapshot, so nothing is held after a restart. |
If you need a specific audit-retention window for a compliance reason, that is a deployment setting rather than an API one — ask and we will configure it for your tenant.
Self-host or hosted?
The engine is open source under Apache-2.0 at PreAgile/reputation-pool: scoring, the four states and their transitions, the cooldown curve, lease fencing, the selection strategy, the gRPC contract, and a PostgreSQL persistence adapter. Self-hosting is a legitimate choice, and this service does not fork the engine — it consumes the published artifact, so what you would run is the same code.
| Self-hosted engine | Hosted API | |
|---|---|---|
| The decision logic | Yes — identical | Yes — identical |
| You operate | The process, PostgreSQL, upgrades, backups | Nothing |
| Multi-tenant isolation | You build it | Built in — pool, audit trail, and event stream per tenant |
| API keys | You build it | Issue, hashed storage, rotation, instant revocation |
| Dashboard, audit queries, score curves | Not included — the trail is write-only upstream | Included |
| Usage metering and alerting | You build it | Included |
Rough rule: if you want the behaviour and already run stateful services, self-host. If you want the behaviour plus keys, tenancy, an audit trail you can query, and somebody else on call, use the hosted API.
Can I migrate between them?
The reputation model is the same either way and the gRPC contract is the engine's, not ours, so client code ports across by changing the address and the auth header. Reputation state does not transfer today — pools warm up again from live traffic, which for most workloads takes hours rather than days.
Where do I report a bug?
It depends on which half is wrong, and the split is the same one described in Introduction.
Engine behaviour → the public repository
File it at PreAgile/reputation-pool if it is about what the engine decides:
- a state transition that fires when it should not, or does not when it should;
- the cooldown curve, the score penalties, or the exponential backoff;
- selection — which candidate gets picked, and how weighting behaves;
- lease semantics: fencing tokens, expiry, renew and release;
- the gRPC contract and message shapes in
advisor.proto.
These belong upstream because the fix belongs in code everyone runs, and because the discussion is worth having in public. A hosted-only patch would be a fork of the exact logic you are meant to be able to audit.
Hosting behaviour → us
Write to digle117@gmail.com if it is about running the service:
- authentication, API keys, JWTs, the login flow;
- tenant isolation, or seeing anything you should not;
- the REST control plane, the dashboard, metering, or the audit read side;
- availability, latency, deployments.
Not sure which side it is? Email us. Misrouting an engine bug costs one forwarded message; sitting on it costs more.
Anything else
Why can I not reach the gRPC data plane on your host?
Because it is not published. Compose binds port 9093 to 127.0.0.1 and the reverse proxy has no gRPC route and no TLS termination for one. That binding is also load-bearing: the login throttle trusts X-Forwarded-For on the premise that the app is unreachable except through the proxy, so opening the data plane is a redesign of that defence rather than a port change. Until it happens, Quickstart runs the loop against a stack you start, and the client code is identical apart from the address and the channel credentials.
Is there a REST equivalent of Acquire and Report?
Not today. The data plane is gRPC only — the control plane is REST. If an HTTP data plane is what stands between you and using this, tell us; it is a known onboarding cost, not a principled refusal.
Can I scrape Prometheus metrics?
The service exposes a Prometheus endpoint, but it is not routed to the public internet — the trust boundary is the network, so only in-cluster scrapers reach it. Customer-facing metrics access is not available yet; the dashboard and GET /api/usage are the supported views.
Is there self-serve signup?
No. Tenants are onboarded by hand today, deliberately — each pool gets set up with someone watching. Write to digle117@gmail.com with a sentence about your workload.
Are these docs available in Korean?
Not yet — the docs are English-only for now, while the marketing site is available in both English and Korean. Korean documentation is planned.