forgelib 1.1.0

The standard library for agent-built SaaS: hardened infra primitives on Postgres
Documentation
{
  "primitive": "ratelimit",
  "scenarios": [
    {
      "name": "check_decrements_then_denies",
      "note": "The full IETF decision (allowed/limit/remaining/reset_after/retry_after) must come back in every language.",
      "steps": [
        { "op": "ratelimit.check", "args": { "bucket": "b", "key": "u", "max": 2, "per_seconds": 60 },
          "expect": { "shape": { "allowed": true, "limit": 2, "remaining": { "$type": "number" }, "reset_after_seconds": { "$type": "number" }, "retry_after_seconds": null } } },
        { "op": "ratelimit.check", "args": { "bucket": "b", "key": "u", "max": 2, "per_seconds": 60 },
          "expect": { "shape": { "allowed": true } } },
        { "op": "ratelimit.check", "args": { "bucket": "b", "key": "u", "max": 2, "per_seconds": 60 },
          "expect": { "shape": { "allowed": false, "retry_after_seconds": { "$type": "number" } } } }
      ]
    },
    {
      "name": "namespace_isolation",
      "note": "ratelimit counters are namespaced today (one of kv/ratelimit/blob); the same bucket+key under two namespaces must not share a counter.",
      "steps": [
        { "op": "ratelimit.check", "args": { "bucket": "b", "key": "u", "max": 1, "per_seconds": 60 }, "namespace": "app-a", "expect": { "shape": { "allowed": true } } },
        { "op": "ratelimit.check", "args": { "bucket": "b", "key": "u", "max": 1, "per_seconds": 60 }, "namespace": "app-a", "expect": { "shape": { "allowed": false } } },
        { "op": "ratelimit.check", "args": { "bucket": "b", "key": "u", "max": 1, "per_seconds": 60 }, "namespace": "app-b", "expect": { "shape": { "allowed": true } } }
      ]
    },
    {
      "name": "weighted_reservation_refunds_unused_units_once",
      "steps": [
        { "op": "ratelimit.check", "args": { "bucket": "budget", "key": "tenant", "max": 10, "per_seconds": 3600, "cost": 4 }, "expect": { "shape": { "allowed": true, "remaining": 6 } } },
        { "op": "ratelimit.reserve", "args": { "bucket": "budget", "key": "tenant", "max": 10, "per_seconds": 3600, "units": 5, "ttl_seconds": 60 }, "as": "reservation", "expect": { "shape": { "state": "pending", "reserved_units": 5 } } },
        { "op": "ratelimit.commit", "args": { "reservation_id": { "$ref": "reservation.id" }, "actual_units": 2 }, "expect": { "shape": { "state": "committed", "committed_units": 2 } } },
        { "op": "ratelimit.commit", "args": { "reservation_id": { "$ref": "reservation.id" }, "actual_units": 2 }, "expect": { "shape": { "state": "committed", "committed_units": 2 } } },
        { "op": "ratelimit.check", "args": { "bucket": "budget", "key": "tenant", "max": 10, "per_seconds": 3600, "cost": 4 }, "expect": { "shape": { "allowed": true, "remaining": 0 } } },
        { "op": "ratelimit.release", "args": { "reservation_id": { "$ref": "reservation.id" } }, "expect": { "error": "Precondition" } }
      ]
    },
    {
      "name": "sliding_window_algo_selectable",
      "note": "The algo param ('token_bucket' default | 'sliding_window') must be selectable in every language and still admit then deny within one window.",
      "steps": [
        { "op": "ratelimit.check", "args": { "bucket": "sw", "key": "u", "max": 2, "per_seconds": 60, "algo": "sliding_window" },
          "expect": { "shape": { "allowed": true, "limit": 2, "remaining": { "$type": "number" } } } },
        { "op": "ratelimit.check", "args": { "bucket": "sw", "key": "u", "max": 2, "per_seconds": 60, "algo": "sliding_window" },
          "expect": { "shape": { "allowed": true } } },
        { "op": "ratelimit.check", "args": { "bucket": "sw", "key": "u", "max": 2, "per_seconds": 60, "algo": "sliding_window" },
          "expect": { "shape": { "allowed": false, "retry_after_seconds": { "$type": "number" } } } },
        { "op": "ratelimit.check", "args": { "bucket": "sw", "key": "u", "max": 2, "per_seconds": 60, "algo": "bogus" },
          "expect": { "error": "Invalid" } }
      ]
    }
  ]
}