website·Indexed 31 days ago
https://tryforge.devAn in-process infrastructure library providing eight backend primitives—including Key-value stores, Queues, Pub/sub, Blob storage, Auth, and Rate limiting—with a versioned contract across Rust, JavaScript, Python, and Go. Forge offers cross-language API stability, PostgreSQL-centered production models, and integration recipes for frameworks like Axum, Hono, Express, FastAPI, and Django ASGI.
Forge is an in-process infrastructure library for application backends (Rust, JS, Python, Go) that uses PostgreSQL as the durable system of record. It provides bounded primitives but does not manage application-level concerns.
Forge owns:
The Application owns:
backendCapabilities of the specific backend being used.Forge allows you to schedule one-time delayed tasks using schedule_at (or .at() in Rust) and recurring tasks using schedule_cron (or .cron() in Rust).
Important: Schedules only fire when the scheduler is ticked. The loop that ticks the scheduler is also the recommended location to run Forge's maintenance sweep. Refer to the Operations documentation for the specific loop implementation required on every replica.
# Schedule a one-time task to expire a link in one hour
await forge.schedule_at(now_ms + 3_600_000, "expire", json.dumps({"slug": slug}))
# Schedule a daily report at midnight
await forge.schedule_cron("nightly-report", "0 0 * * *", "reports", "{}")use std::time::{Duration, SystemTime};
use forgelib::ScheduleOpts;
// Schedule a one-time task to expire a link in one hour
let when = SystemTime::now() + Duration::from_secs(3600);
forge.schedule().at(when, "expire", payload.into(), ScheduleOpts::new()).await?;
// Schedule a daily report at midnight
forge.schedule().cron("nightly-report", "0 0 * * *", "reports",
b"{}".to_vec().into(), ScheduleOpts::new()).await?;validateSession in middleware to resolve a bearer token or session cookie to a user ID. To log a user out, use revokeSession to invalidate the token immediately so it no longer resolves to a user.// Rust Example
// Middleware: resolve bearer token to a session, else 401
let Some(session) = forge.auth().validate_session(bearer).await? else {
return unauthorized();
};
let user_id = session.user_id;
// Logout: revoke the session so the token stops resolving
forge.auth().revoke_session(bearer).await?;Forge provides built-in metrics for operations, pool use, retries, queue/worker state, and more. Use renderPrometheus() (or language equivalent) to emit Prometheus-formatted text. This does not require a separate collector or exporter installation.
Note: Forge uses fixed low-cardinality labels. High-cardinality data like user IDs, job IDs, or model outputs are never used as labels or span attributes to prevent metric explosion.
API-key secrets are returned once; Forge stores only the hash. Implement bounded expiries, explicit scopes, and minimal non-secret metadata. Enforce owner and scope checks in the application policy after verification.
One-time tokens must be purpose-scoped, expiring, hashed, and atomically consumed. Use them for opaque return state or record IDs rather than authorization policy. Tokens cannot be replayed for different purposes or recovered once consumed.
ack) success or negatively acknowledge (nack) failure to trigger a retry.// In the request handler: cheap now, the rest later
await forge.kvIncr(`clicks:${slug}`, 1);
await forge.queue<{ slug: string } ("clicks").enqueue({ slug }, { maxAttempts: 3 });
// In the worker: process the job
await forge.worker<{ slug: string }>( "clicks", async (job) => {
await handle(forge, job.payload);
});// Typing indicator (Live only)
app.post("/api/rooms/:room/typing", async (c) => {
await forge.topic(`chat:${c.req.param("room")}`).publish({ type: "typing", userId });
return c.body(null, 204);
});
// Presence heartbeat
app.post("/api/heartbeat", async (c) => {
const userId = await requireUser(c);
await forge.kvSet(`presence:${userId}`, "1", 30); // expires in 30s
await forge.topic("presence").publish({ userId, online: true });
return c.body(null, 204);
});forge.rate_limit_check to prevent brute-force attacks on signup/login, forge.hash_password and forge.verify_password for security, and forge.create_session to manage user state. Use forge.kv_set with the nx=True (set if not present) parameter to ensure email uniqueness during registration.# Example Signup Logic
@api.post("/api/signup", status_code=201)
async def signup(request: Request, body: Credentials) -> dict[str, Any]:
forge = request.app.state.forge
email = body.email.strip().lower()
# Rate limiting
limit = await forge.rate_limit_check("links-auth", email, 20, 60.0, True)
if not limit.allowed:
raise HTTPException(429, "too many attempts")
user = {"id": str(uuid.uuid4()), "email": email,
"password_hash": await forge.hash_password(body.password)}
# Atomic check if email exists
if not await forge.kv_set(user_email_key(email), json.dumps(user), None, True):
raise HTTPException(409, "email already registered")
token = await forge.create_session(user["id"], 1800.0, 604800.0)
return {"token": token, "user": {"id": user["id"], "email": email}}