Prerequisites

What a Fencing Token Is

A fencing token is a strictly increasing number issued with every grant of exclusive access. The protected resource records the highest token it has accepted and refuses anything lower.

The Gap Tokens Close

Every coordination mechanism shares one structural weakness: the interval between being granted permission and using it. Nothing the client does can eliminate that interval.

The Sequence Tokens Prevent

Monotonicity Is the Whole Property

The token's only requirement is that it strictly increases across grants. Everything else about it is incidental.

Generating Tokens

CREATE TABLE lock_grants (
    resource       VARCHAR(160) PRIMARY KEY,
    holder_id      VARCHAR(80)  NOT NULL,
    fencing_token  BIGINT       NOT NULL DEFAULT 0,
    granted_at     TIMESTAMP    NOT NULL,
    expires_at     TIMESTAMP    NOT NULL
);

-- Atomic grant with token increment
UPDATE lock_grants
SET holder_id     = :holder_id,
    fencing_token = fencing_token + 1,
    granted_at    = CURRENT_TIMESTAMP,
    expires_at    = CURRENT_TIMESTAMP + (:ttl_ms * INTERVAL '1 millisecond')
WHERE resource = :resource
  AND (expires_at < CURRENT_TIMESTAMP OR holder_id = :holder_id)
RETURNING fencing_token, expires_at;

Validating at the Resource

Validation must happen where the write lands, in the same atomic operation as the write. A separate check-then-write introduces the very gap the token exists to close.

-- Correct: comparison and write are one atomic operation
UPDATE account_balances
SET balance       = balance + :delta,
    fencing_token = :token,
    updated_at    = CURRENT_TIMESTAMP
WHERE account_id    = :account_id
  AND fencing_token <= :token;

-- Zero rows affected means a stale writer was rejected

class FencedResource {
    constructor(store) {
        this.store = store;
    }

    async apply(resourceId, mutation, token) {
        const result = await this.store.conditionalUpdate({
            id: resourceId,
            set: { ...mutation, fencingToken: token },
            condition: { fencingToken: { lessThanOrEqual: token } }
        });

        if (result.rowsAffected === 0) {
            const current = await this.store.readToken(resourceId);

            return {
                accepted: false,
                reason: "stale-token",
                presented: token,
                required: current
            };
        }

        return { accepted: true, token };
    }
}

Greater-Than or Greater-Than-Or-Equal

Fencing Different Resource Types

Fencing a Downstream Service

async function callFencedService(client, request, token) {
    const response = await client.post("/apply", {
        headers: {
            "X-Fencing-Token": String(token),
            "X-Resource-Id": request.resourceId
        },
        body: request.payload
    });

    if (response.status === 409) {
        return {
            accepted: false,
            reason: "fenced by downstream",
            requiredToken: Number(response.headers.get("X-Required-Token"))
        };
    }

    return { accepted: true, result: response.body };
}

function fencingMiddleware(store) {
    return async function (request, response, next) {
        const token = Number(request.headers["x-fencing-token"]);
        const resourceId = request.headers["x-resource-id"];

        if (!Number.isFinite(token)) {
            return response.status(400).json({
                error: "missing or invalid fencing token"
            });
        }

        const highest = await store.highestToken(resourceId);

        if (token < highest) {
            response.setHeader("X-Required-Token", String(highest));
            return response.status(409).json({
                error: "stale fencing token",
                presented: token,
                required: highest
            });
        }

        request.fencingToken = token;
        return next();
    };
}

When Fencing Is Impossible

Many external systems accept any authenticated write with no version check. Exclusion cannot be guaranteed for these, so the goal shifts to limiting damage.

async function callUnfenceableExternal(external, request, token) {
    const guard = await localStore.conditionalUpdate({
        id: request.resourceId,
        set: { pendingToken: token, pendingAt: Date.now() },
        condition: { pendingToken: { lessThanOrEqual: token } }
    });

    if (guard.rowsAffected === 0) {
        return { accepted: false, reason: "fenced locally before external call" };
    }

    return await external.submit(request.payload, {
        idempotencyKey: `${request.resourceId}:${token}`
    });
}

Token Scope

A token is meaningful only within the scope its issuer covers. Comparing tokens from different issuers or different resources produces nonsense.

{
    "resourceId": "shard-0042",
    "fencing": {
        "token": 1847,
        "issuer": "lock-service",
        "scope": "resource:shard-0042",
        "issuedAt": "2026-09-24T06:14:22Z"
    }
}

Fencing and Version Guards

Fencing tokens resemble optimistic concurrency version guards, but they answer different questions and can coexist.

-- Both guards applied together
UPDATE documents
SET content       = :content,
    version       = version + 1,
    fencing_token = :fencing_token
WHERE document_id    = :document_id
  AND version        = :expected_version
  AND fencing_token <= :fencing_token;

Failure Modes

Monitoring

Verification

describe("fencing token enforcement", function () {
    it("rejects a lower token after a higher one is accepted", async function () {
        await resource.apply("res-1", { value: "b" }, 42);

        const stale = await resource.apply("res-1", { value: "a" }, 41);

        expect(stale.accepted).toBe(false);
        expect(stale.required).toBe(42);
    });

    it("accepts repeated writes with the same token", async function () {
        await resource.apply("res-1", { value: "x" }, 50);
        const again = await resource.apply("res-1", { value: "y" }, 50);

        expect(again.accepted).toBe(true);
    });

    it("issues strictly increasing tokens across grants", async function () {
        const tokens = [];

        for (let i = 0; i < 20; i += 1) {
            const grant = await lockService.acquire("res-1", `client-${i}`);
            tokens.push(grant.fencingToken);
            await lockService.forceExpire("res-1");
        }

        for (let i = 1; i < tokens.length; i += 1) {
            expect(tokens[i]).toBeGreaterThan(tokens[i - 1]);
        }
    });

    it("preserves monotonicity across issuer restart", async function () {
        const before = await lockService.acquire("res-1", "client-a");

        await faultInjector.restartIssuer();

        const after = await lockService.acquire("res-1", "client-b");

        expect(after.fencingToken).toBeGreaterThan(before.fencingToken);
    });
});

Common Design Mistakes

System Design Interview Discussion

Design Checklist

Knowledge Check

Summary

A fencing token is a strictly increasing number issued with each grant of exclusive access, recorded by the resource and used to reject any writer presenting a lower value. It closes the gap that no coordination mechanism can close on its own.

That gap exists because a client cannot observe its own suspension. A paused process perceives no elapsed time, so it cannot detect that its lease expired and another holder has since acted. Shorter leases and larger margins reduce the probability without ever reaching zero.

Monotonicity is the only property that matters, and it requires a single durable authority. Timestamps fail because of clock skew, and in-memory counters fail because restart reissues consumed values. Consensus log indices, leader terms, and database sequences all work.

Validation must occur at the resource, in the same atomic operation as the write, and the token must propagate across every hop in the write path. Where a resource cannot be fenced, the goal shifts from prevention to damage limitation through idempotency keys, local guards, and reconciliation.