DEV Community

robertmiller4179
robertmiller4179

Posted on

Node.js Cron Cleanup: 3 Stages for Expired User Sessions, Tokens, and Postgres Queues

Short answer: use Node.js cron to request cleanup, not to perform it; claim expired sessions and tokens in bounded Postgres batches, make every delete and queue write idempotent, and expose a public webhook endpoint only as an authenticated trigger. For a weekly property-management digest, this favors predictable cost over instant cleanup while keeping the consumer free to retry.

I've been paged for missed jobs and duplicate deliveries. The invariant from those incidents is plain: a schedule is evidence that a trigger was attempted, not evidence that the work completed exactly once. If the digest reads “active customers” while cleanup is racing it, an expired session can leak into the audience calculation or the same customer can be queued twice.

So the design needs three durable stages: claim cleanup work, apply expiry, then enqueue the digest from the resulting active set. Cron starts the sequence. It doesn't own the sequence.

How should a Node.js cron cleanup handle expired user sessions, tokens, and a queue?

Treat time as an input and progress as data. The Node.js process calculates a cutoff, creates a run identifier, and sends those values to the cleanup handler. The handler claims a small batch of rows, marks or deletes only records whose expiry is at or before that cutoff, and records enough progress for another consumer to resume the run. Once no eligible rows remain, a separate step builds the weekly digest audience.

That order matters. Imagine a property manager with 18 buildings and a customer whose token expires at 09:00:00 UTC. A scheduler starts at that instant, times out after submitting work, and retries. If “delete expired token” and “enqueue digest” share one unguarded loop, both attempts may enqueue the customer. If each run instead carries a stable key such as weekly-digest:2026-W36, the consumer can accept both deliveries while committing only one audience record per customer and period. The exact batch size is workload-specific; I'm not sure a value chosen from row count alone will hold under production lock contention, so settle it with query latency and lock-wait measurements from the target database.

Keep the states boring:

  1. requested: the scheduler or webhook accepted a run key and cutoff.
  2. cleaning: consumers repeatedly claim bounded batches and expire eligible records.
  3. ready: cleanup is complete, so the digest audience can be enqueued once per customer and run key.

No magic.

The public webhook endpoint should return after it has durably accepted the run, rather than holding the connection through every deletion. Authenticate it, reject a reused request identifier with a conflict response, validate that the cutoff is within the allowed scheduling window, and store the request before acknowledging it. A manual run and the regular Node.js cron path should call the same entry point; otherwise the runbook tests one path while production uses another.

Put the preventative path at the transaction boundary

The useful abstraction is not a particular queue. It is a store that can claim eligible rows and commit a run marker atomically. The following Go handler shows the boundary behind a generic /hooks/session-cleanup endpoint. A Node.js cron caller can invoke it over HTTP, but scheduling language and worker language do not change the contract.

package cleanup

import (
    "context"
    "encoding/json"
    "net/http"
    "time"
)

type Request struct {
    RunKey string    `json:"run_key"`
    Cutoff time.Time `json:"cutoff"`
}

type Store interface {
    // AcceptRun inserts the stable run key and returns false when it already exists.
    AcceptRun(ctx context.Context, runKey string, cutoff time.Time) (bool, error)
}

type Handler struct {
    Store Store
    Now   func() time.Time
}

func (h Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
    if r.Method != http.MethodPost {
        http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
        return
    }

    var req Request
    if err := json.NewDecoder(r.Body).Decode(&req); err != nil || req.RunKey == "" {
        http.Error(w, "invalid request", http.StatusBadRequest)
        return
    }
    if req.Cutoff.After(h.Now().UTC().Add(5 * time.Minute)) {
        http.Error(w, "cutoff outside allowed window", http.StatusBadRequest)
        return
    }

    accepted, err := h.Store.AcceptRun(r.Context(), req.RunKey, req.Cutoff.UTC())
    if err != nil {
        http.Error(w, "request could not be accepted", http.StatusServiceUnavailable)
        return
    }
    if !accepted {
        http.Error(w, "run key already accepted", http.StatusConflict)
        return
    }

    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(http.StatusAccepted)
    json.NewEncoder(w).Encode(map[string]string{"run_key": req.RunKey})
}
Enter fullscreen mode Exit fullscreen mode

The database implementation should make run_key unique. Its claim operation should lock a limited set of eligible records, update them in the same transaction, and then release the locks quickly. Keep email rendering and network delivery outside that transaction. A slow downstream call inside the claim transaction increases lock time and turns a delivery problem into a database-contention problem.

Idempotency also belongs at the last durable write. Give the digest queue an uniqueness rule over (run_key, customer_id). A consumer may then crash after sending but before acknowledging, so the external delivery still needs its own stable message identifier where the email provider supports one. Exactly-once execution is not the promise here. The practical promise is that retries converge on one durable intent, and duplicate side effects are constrained at each boundary.

Choose the state store by the failure you can operate

Postgres is a sensible default when sessions, tokens, customer activity, and digest intent already live there. It keeps the cleanup predicate and audience snapshot close to the source of truth, and one transaction can protect claims and run records. The catch is that large delete bursts create database work at the same place serving customer traffic. Use bounded batches, schedule away from known peaks, observe lock waits, and consider marking rows expired before slower physical deletion.

Redis can move hot expiry checks away from relational queries and can fit short-lived token state. It also adds a second consistency boundary if the authoritative customer status remains in Postgres. A key disappearing from Redis does not, by itself, prove that a relational audience query observed the corresponding state change. Stick with a database-backed queue when auditability and one transactional boundary matter more than sub-second expiry.

Temporal represents another operating model: durable workflow state, retries, and long-running coordination live in a workflow system rather than in a cron callback. That can be appropriate when cleanup has several remote steps, waits, or compensating actions. It is not suitable when the team wants one modest weekly batch and cannot justify another control plane. Plain cron is the smallest option, but it needs an external durable run record because the schedule alone cannot answer “which batch committed?”

Approach Useful when Operational price Poor fit when
Postgres claims Source data and audit records share one database Cleanup competes for database locks and I/O The database is already near its workload ceiling
Redis-backed queue Fast ephemeral coordination is already operated Reconciliation with relational truth is explicit work A single auditable transaction is required
Durable workflow Runs span retries, waits, and multiple services The team owns another execution model One short weekly job is the whole requirement
Cron plus run table The flow is small and database-centered Recovery logic remains application code Work has many remote, long-lived stages

These are alternatives, not a ranking. Latency points toward Redis-backed coordination or a continuously running consumer; cost and operational simplicity often point toward a weekly Postgres batch. Your mileage may vary because the decisive number is rarely raw row count. It is how much cleanup work can overlap the foreground workload without breaking its latency objective.

Observe outcomes, not scheduler heartbeats

A green cron heartbeat says little. Alert on the age of the oldest accepted but unfinished run, the count of expired records remaining past the cutoff, duplicate run-key rejections, batch duration, lock-wait time, queue depth, and digest intents without a terminal delivery state. Put run_key, cutoff, batch_id, and customer_id in structured logs, while keeping tokens and session secrets out.

For the weekly digest, define a completion objective in business terms: cleanup reaches ready before the audience snapshot deadline, and every eligible customer has one durable digest intent for the run key. Then test the ugly transitions. Start the same run twice. Stop a consumer after it claims a batch. Advance the clock across the cutoff. Delay the queue. Run cleanup while a customer changes active status. Each test should assert stored state, not merely an HTTP response.

The runbook should have one replay command keyed by run_key, one query that shows current stage and remaining work, and one documented way to pause consumers without deleting the run record. I've learned to distrust a recovery procedure that begins by editing timestamps. Preserve the original cutoff; a replay should finish the same decision, not silently calculate a new audience.

Where this pattern stops fitting

Weekly cleanup tolerates minutes of delay, which makes bounded database batches attractive. Don't use this pattern for security revocation that must take effect immediately, for jobs requiring coordinated compensation across many remote systems, or when regulation requires a dedicated immutable execution history. Use synchronous revocation checks for the first case and evaluate a durable workflow or purpose-built audit system for the latter cases.

The decision rule is compact: choose the least complex mechanism that preserves a durable run key, an atomic claim, bounded retries, and an observable completion condition. The scheduler wakes the system up. Stored state tells the operator what actually happened.

References

Sources

Top comments (0)