Reference

Security & In-Process Crons

Every security boundary in nextgin is designed to fail closed so misconfiguration never silently opens an endpoint.

Fail-Closed HTTP Primitives

Strict JSON Parsing (ReadJSON)

nextgin.ReadJSON(w, r, &dto) enforces DefaultMaxBodyBytes (1 MiB), rejects unknown or malformed JSON, and rejects trailing tokens after the first JSON value.

var req CreateOrderRequest
if err := nextgin.ReadJSON(w, r, &req); err != nil {
    nextgin.WriteError(w, http.StatusBadRequest, err.Error())
    return
}

Exact-Byte Payment Webhooks (ReadRawBody)

Never decode Stripe, Paystack, or GitHub webhook bodies with ReadJSON before verifying signatures. Use ReadRawBody to read exact wire bytes with a strict byte cap:

raw, err := nextgin.ReadRawBody(w, r, 256<<10) // 256 KiB cap
if err != nil {
    nextgin.WriteError(w, http.StatusBadRequest, "invalid body")
    return
}
// Verify HMAC-SHA256 using crypto/hmac.Equal before json.Unmarshal

Strict CORS & Proxy Trust

  • nextgin.CORS(nextgin.CORSConfig{AllowedOrigins: []string{"https://app.example.com"}}) panics at startup if AllowedOrigins is empty or contains "*".
  • X-Forwarded-For and X-Forwarded-Proto are ignored unless TrustForwardedHeaders: true is explicitly configured behind a trusted reverse proxy.

Per-IP Rate Limiting (RateLimit)

Built-in token-bucket limiter with automatic idle eviction and 429 Too Many Requests + Retry-After headers:

auth := api.Group("/auth")
auth.Use(nextgin.RateLimit(5, 10)) // 5 req/sec, burst 10

Internal SSR Auth (RequireInternal)

Protect Go endpoints meant only for Next.js Server Components / Server Actions:

internal := api.Group("/internal")
internal.Use(nextgin.RequireInternal())

If NEXTGIN_INTERNAL_SECRET is unset, RequireInternal() returns 401 Unauthorized for every request.


Reliable In-Process Crons

Every cron job in nextgin is an authenticated HTTP route registered under /_nextgin/cron/<name>:

app.Cron("expire-carts", "* * * * *", func(w http.ResponseWriter, r *http.Request) {
    if err := r.Context().Err(); err != nil {
        nextgin.WriteError(w, http.StatusServiceUnavailable, "shutting down")
        return
    }
    if err := cartService.ExpireStale(r.Context()); err != nil {
        nextgin.WriteError(w, http.StatusInternalServerError, err.Error())
        return
    }
    w.WriteHeader(http.StatusNoContent)
})

Key Guarantees

  1. Fail-closed auth: Only the per-process internal bearer token or CRON_SECRET can invoke /_nextgin/cron/*.
  2. Excluded from public exports: /_nextgin/* routes are never exported to public Vercel rewrite tables.
  3. Graceful shutdown: Always pass r.Context() to DB queries and HTTP calls so SIGTERM cancels long jobs cleanly.
  4. Multi-replica safety: Attach a CronLocker (PostgreSQL advisory lock or Redis SET NX) in nextgin.Config so rolling deploys never double-run a tick.