actor-ts 0.9.1 → 0.11.0

package/dist/coordination/LeaseOptions.js

@@ -0,0 +1,89 @@
+import { OptionsBuilder } from '../util/OptionsBuilder.js';
+import { OptionsValidator } from '../util/OptionsValidator.js';
+/**
+ * Fluent builder for {@link LeaseOptionsType} — the common construction-time
+ * options every {@link Lease} backend shares.  The concrete
+ * `KubernetesLeaseOptionsBuilder` subclass extends this with the K8s-specific
+ * `withX(...)` methods.
+ *
+ *     new InMemoryLease(
+ *       LeaseOptions.create().withName('singleton').withOwner(nodeId).withTtlMs(10_000),
+ *     );
+ *
+ * Generic over `T extends LeaseOptionsType` so `KubernetesLeaseOptionsBuilder`
+ * can inherit these six setters while adding its own — same shape as the
+ * broker `BrokerOptionsBuilder<T>` base.  The `as keyof T` casts pay for
+ * writing the shared setters once against the generic; concrete subclasses
+ * stay type-safe because their extra methods target concrete field types.
+ */
+export class LeaseOptionsBuilder extends OptionsBuilder {
+    /** Start a fresh builder.  Equivalent to `new LeaseOptionsBuilder()`. */
+    static create() {
+        return new LeaseOptionsBuilder();
+    }
+    /** Lease name — unique identifier within the namespace. */
+    withName(name) {
+        return this.set('name', name);
+    }
+    /** Identifier of the holder (pod name / host name / uuid). */
+    withOwner(owner) {
+        return this.set('owner', owner);
+    }
+    /** Time-to-live in ms — the backend auto-expires if we fail to renew. */
+    withTtlMs(ttlMs) {
+        return this.set('ttlMs', ttlMs);
+    }
+    /** How often to renew (< ttlMs — typically ttl/3). */
+    withRenewalIntervalMs(renewalIntervalMs) {
+        return this.set('renewalIntervalMs', renewalIntervalMs);
+    }
+    /** Max attempts for a single `acquire()` before returning false. */
+    withAcquireRetries(acquireRetries) {
+        return this.set('acquireRetries', acquireRetries);
+    }
+    /** Delay between acquire retries. */
+    withAcquireRetryDelayMs(acquireRetryDelayMs) {
+        return this.set('acquireRetryDelayMs', acquireRetryDelayMs);
+    }
+}
+/**
+ * Validates resolved lease settings.  Generic over `T extends LeaseOptionsType`
+ * so `KubernetesLeaseOptionsValidator` can extend it; the shared fields are
+ * checked imperatively in {@link commonRules} (a cast to `LeaseOptionsType`
+ * sidesteps the generic-key friction, mirroring `BrokerOptionsValidator`).
+ * Only present values are checked — an unset optional passes.
+ */
+export class LeaseOptionsValidator extends OptionsValidator {
+    constructor(optionsName = 'LeaseOptions') {
+        super(optionsName);
+    }
+    rules(s) {
+        this.commonRules(s);
+    }
+    commonRules(s) {
+        const opts = s;
+        if (opts.name !== undefined && (typeof opts.name !== 'string' || opts.name.length === 0)) {
+            this.fail('name', 'must be a non-empty string', opts.name);
+        }
+        if (opts.owner !== undefined && (typeof opts.owner !== 'string' || opts.owner.length === 0)) {
+            this.fail('owner', 'must be a non-empty string', opts.owner);
+        }
+        if (opts.ttlMs !== undefined && (typeof opts.ttlMs !== 'number' || !Number.isFinite(opts.ttlMs) || opts.ttlMs <= 0)) {
+            this.fail('ttlMs', 'must be a positive finite number', opts.ttlMs);
+        }
+        if (opts.renewalIntervalMs !== undefined &&
+            (typeof opts.renewalIntervalMs !== 'number' || !Number.isFinite(opts.renewalIntervalMs) || opts.renewalIntervalMs <= 0)) {
+            this.fail('renewalIntervalMs', 'must be a positive finite number', opts.renewalIntervalMs);
+        }
+        if (opts.acquireRetries !== undefined && (!Number.isInteger(opts.acquireRetries) || opts.acquireRetries < 0)) {
+            this.fail('acquireRetries', 'must be an integer >= 0', opts.acquireRetries);
+        }
+        if (opts.acquireRetryDelayMs !== undefined &&
+            (typeof opts.acquireRetryDelayMs !== 'number' || !Number.isFinite(opts.acquireRetryDelayMs) || opts.acquireRetryDelayMs < 0)) {
+            this.fail('acquireRetryDelayMs', 'must be a non-negative finite number', opts.acquireRetryDelayMs);
+        }
+    }
+}
+/** Value alias so `LeaseOptions.create()` / `new LeaseOptions()` resolve to the builder. */
+export const LeaseOptions = LeaseOptionsBuilder;
+//# sourceMappingURL=LeaseOptions.js.map

package/dist/coordination/LeaseOptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LeaseOptions.js","sourceRoot":"","sources":["../../src/coordination/LeaseOptions.ts"],"names":[],"mappings":"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"}

package/dist/coordination/index.d.ts

@@ -1,5 +1,8 @@
-export type { Lease, LeaseSettings } from './Lease.js';
+export type { Lease } from './Lease.js';
+export { LeaseOptions, LeaseOptionsBuilder, LeaseOptionsValidator } from './LeaseOptions.js';
+export type { LeaseOptionsType } from './LeaseOptions.js';
 export { InMemoryLease, inMemoryLeaseStore } from './leases/InMemoryLease.js';
 export { KubernetesLease } from './leases/KubernetesLease.js';
-export type { KubernetesLeaseSettings } from './leases/KubernetesLease.js';
+export { KubernetesLeaseOptions, KubernetesLeaseOptionsBuilder, KubernetesLeaseOptionsValidator } from './leases/KubernetesLeaseOptions.js';
+export type { KubernetesLeaseOptionsType } from './leases/KubernetesLeaseOptions.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/coordination/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/coordination/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC9E,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAC9D,YAAY,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/coordination/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAC7F,YAAY,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC9E,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,EAAE,sBAAsB,EAAE,6BAA6B,EAAE,+BAA+B,EAAE,MAAM,oCAAoC,CAAC;AAC5I,YAAY,EAAE,0BAA0B,EAAE,MAAM,oCAAoC,CAAC"}

package/dist/coordination/index.js

@@ -1,3 +1,5 @@
+export { LeaseOptions, LeaseOptionsBuilder, LeaseOptionsValidator } from './LeaseOptions.js';
 export { InMemoryLease, inMemoryLeaseStore } from './leases/InMemoryLease.js';
 export { KubernetesLease } from './leases/KubernetesLease.js';
+export { KubernetesLeaseOptions, KubernetesLeaseOptionsBuilder, KubernetesLeaseOptionsValidator } from './leases/KubernetesLeaseOptions.js';
 //# sourceMappingURL=index.js.map

package/dist/coordination/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/coordination/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC9E,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/coordination/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAE7F,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC9E,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,EAAE,sBAAsB,EAAE,6BAA6B,EAAE,+BAA+B,EAAE,MAAM,oCAAoC,CAAC"}

package/dist/coordination/leases/InMemoryLease.d.ts

@@ -1,14 +1,18 @@
-import type { Lease, LeaseSettings } from '../Lease.js';
+import type { Lease } from '../Lease.js';
+import type { LeaseOptions } from '../LeaseOptions.js';
 interface LeaseRecord {
     readonly name: string;
     owner: string;
     expiresAt: number;
+    /** Monotonic counter bumped on every (re)acquire — backs the fencing token. */
+    version: number;
 }
 /** Global registry shared by all InMemoryLeases in the process — simulates a remote store. */
 declare class InMemoryLeaseStore {
     private readonly leases;
-    /** Try to take the lease named `name` for `owner` until `expiresAt`. */
-    tryAcquire(name: string, owner: string, expiresAt: number): boolean;
+    /** Try to take the lease named `name` for `owner` until `expiresAt`.
+     *  Returns the new version number on success, or 0 on failure. */
+    tryAcquire(name: string, owner: string, expiresAt: number): number;
     renew(name: string, owner: string, expiresAt: number): boolean;
     release(name: string, owner: string): void;
     peek(name: string): LeaseRecord | undefined;
@@ -24,13 +28,22 @@ export declare const inMemoryLeaseStore: InMemoryLeaseStore;
  * `KubernetesLease` for that.
  */
 export declare class InMemoryLease implements Lease {
-    private readonly settings;
     private readonly renewalIntervalMs;
     private renewalTimer;
     private held;
     private readonly onLostHandlers;
-    constructor(settings: LeaseSettings);
+    private readonly options;
+    constructor(options?: LeaseOptions);
     acquire(): Promise<boolean>;
+    /**
+     * Fencing-token variant: returns a monotonic version string scoped
+     * to this lease name.  The token is `<lease-name>@v<version>` —
+     * suitable for use as an opaque identifier and ordered by parsing
+     * the trailing `<version>` integer.
+     */
+    acquireWithToken(): Promise<{
+        readonly token: string;
+    } | null>;
     release(): Promise<void>;
     checkAlive(): boolean;
     onLost(handler: (reason: string) => void): () => void;

package/dist/coordination/leases/InMemoryLease.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"InMemoryLease.d.ts","sourceRoot":"","sources":["../../../src/coordination/leases/InMemoryLease.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAExD,UAAU,WAAW;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,8FAA8F;AAC9F,cAAM,kBAAkB;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkC;IAEzD,wEAAwE;IACxE,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO;IAQnE,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO;IAO9D,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAK1C,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;IAM3C,8BAA8B;IAC9B,MAAM,IAAI,IAAI;CACf;AAED,0EAA0E;AAC1E,eAAO,MAAM,kBAAkB,oBAA2B,CAAC;AAE3D;;;;;GAKG;AACH,qBAAa,aAAc,YAAW,KAAK;IAM7B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IALrC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,YAAY,CAA+C;IACnE,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAuC;gBAEzC,QAAQ,EAAE,aAAa;IAI9C,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC;IAe3B,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAO9B,UAAU,IAAI,OAAO;IAErB,MAAM,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI;IAKrD,OAAO,CAAC,gBAAgB;CAczB"}
+{"version":3,"file":"InMemoryLease.d.ts","sourceRoot":"","sources":["../../../src/coordination/leases/InMemoryLease.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,KAAK,EAAE,YAAY,EAAoB,MAAM,oBAAoB,CAAC;AAEzE,UAAU,WAAW;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,8FAA8F;AAC9F,cAAM,kBAAkB;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkC;IAEzD;sEACkE;IAClE,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM;IASlE,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO;IAO9D,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAK1C,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;IAM3C,8BAA8B;IAC9B,MAAM,IAAI,IAAI;CACf;AAED,0EAA0E;AAC1E,eAAO,MAAM,kBAAkB,oBAA2B,CAAC;AAE3D;;;;;GAKG;AACH,qBAAa,aAAc,YAAW,KAAK;IACzC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,YAAY,CAA+C;IACnE,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAuC;IAEtE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmB;gBAE/B,OAAO,GAAE,YAAiB;IAMhC,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC;IAIjC;;;;;OAKG;IACG,gBAAgB,IAAI,OAAO,CAAC;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAgB9D,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAO9B,UAAU,IAAI,OAAO;IAErB,MAAM,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI;IAKrD,OAAO,CAAC,gBAAgB;CAczB"}

package/dist/coordination/leases/InMemoryLease.js

@@ -1,14 +1,17 @@
+import { LeaseOptionsValidator } from '../LeaseOptions.js';
 /** Global registry shared by all InMemoryLeases in the process — simulates a remote store. */
 class InMemoryLeaseStore {
     leases = new Map();
-    /** Try to take the lease named `name` for `owner` until `expiresAt`. */
+    /** Try to take the lease named `name` for `owner` until `expiresAt`.
+     *  Returns the new version number on success, or 0 on failure. */
     tryAcquire(name, owner, expiresAt) {
         const now = Date.now();
         const existing = this.leases.get(name);
         if (existing && existing.owner !== owner && existing.expiresAt > now)
-            return false;
-        this.leases.set(name, { name, owner, expiresAt });
-        return true;
+            return 0;
+        const version = (existing?.version ?? 0) + 1;
+        this.leases.set(name, { name, owner, expiresAt, version });
+        return version;
     }
     renew(name, owner, expiresAt) {
         const existing = this.leases.get(name);
@@ -23,12 +26,12 @@ class InMemoryLeaseStore {
             this.leases.delete(name);
     }
     peek(name) {
-        const r = this.leases.get(name);
-        if (r && r.expiresAt <= Date.now()) {
+        const lease = this.leases.get(name);
+        if (lease && lease.expiresAt <= Date.now()) {
             this.leases.delete(name);
             return undefined;
         }
-        return r;
+        return lease;
     }
     /** Reset — only for tests. */
     _clear() { this.leases.clear(); }
@@ -42,29 +45,40 @@ export const inMemoryLeaseStore = new InMemoryLeaseStore();
  * `KubernetesLease` for that.
  */
 export class InMemoryLease {
-    settings;
     renewalIntervalMs;
     renewalTimer = null;
     held = false;
     onLostHandlers = new Set();
-    constructor(settings) {
-        this.settings = settings;
-        this.renewalIntervalMs = settings.renewalIntervalMs ?? Math.max(100, Math.floor(settings.ttlMs / 3));
+    options;
+    constructor(options = {}) {
+        this.options = options;
+        new LeaseOptionsValidator().validate(this.options);
+        this.renewalIntervalMs = this.options.renewalIntervalMs ?? Math.max(100, Math.floor(this.options.ttlMs / 3));
     }
     async acquire() {
-        const retries = this.settings.acquireRetries ?? 1;
-        const delay = this.settings.acquireRetryDelayMs ?? 50;
+        return (await this.acquireWithToken()) !== null;
+    }
+    /**
+     * Fencing-token variant: returns a monotonic version string scoped
+     * to this lease name.  The token is `<lease-name>@v<version>` —
+     * suitable for use as an opaque identifier and ordered by parsing
+     * the trailing `<version>` integer.
+     */
+    async acquireWithToken() {
+        const retries = this.options.acquireRetries ?? 1;
+        const delay = this.options.acquireRetryDelayMs ?? 50;
         for (let i = 0; i < retries; i++) {
-            const expiresAt = Date.now() + this.settings.ttlMs;
-            if (inMemoryLeaseStore.tryAcquire(this.settings.name, this.settings.owner, expiresAt)) {
+            const expiresAt = Date.now() + this.options.ttlMs;
+            const version = inMemoryLeaseStore.tryAcquire(this.options.name, this.options.owner, expiresAt);
+            if (version > 0) {
                 this.held = true;
                 this.startRenewalLoop();
-                return true;
+                return { token: `${this.options.name}@v${version}` };
             }
             if (i < retries - 1)
                 await sleep(delay);
         }
-        return false;
+        return null;
     }
     async release() {
         if (!this.held)
@@ -74,7 +88,7 @@ export class InMemoryLease {
             clearInterval(this.renewalTimer);
             this.renewalTimer = null;
         }
-        inMemoryLeaseStore.release(this.settings.name, this.settings.owner);
+        inMemoryLeaseStore.release(this.options.name, this.options.owner);
     }
     checkAlive() { return this.held; }
     onLost(handler) {
@@ -85,17 +99,17 @@ export class InMemoryLease {
         this.renewalTimer = setInterval(() => {
             if (!this.held)
                 return;
-            const expiresAt = Date.now() + this.settings.ttlMs;
-            const ok = inMemoryLeaseStore.renew(this.settings.name, this.settings.owner, expiresAt);
+            const expiresAt = Date.now() + this.options.ttlMs;
+            const ok = inMemoryLeaseStore.renew(this.options.name, this.options.owner, expiresAt);
             if (!ok) {
                 this.held = false;
                 if (this.renewalTimer) {
                     clearInterval(this.renewalTimer);
                     this.renewalTimer = null;
                 }
-                for (const h of this.onLostHandlers) {
+                for (const handler of this.onLostHandlers) {
                     try {
-                        h('lease lost during renewal');
+                        handler('lease lost during renewal');
                     }
                     catch { /* swallow */ }
                 }

package/dist/coordination/leases/InMemoryLease.js.map

@@ -1 +1 @@
-{"version":3,"file":"InMemoryLease.js","sourceRoot":"","sources":["../../../src/coordination/leases/InMemoryLease.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"InMemoryLease.js","sourceRoot":"","sources":["../../../src/coordination/leases/InMemoryLease.ts"],"names":[],"mappings":"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"}

package/dist/coordination/leases/KubernetesLease.d.ts

@@ -1,25 +1,5 @@
-import type { Lease, LeaseSettings } from '../Lease.js';
-import { type K8sFetchClient } from './k8sApi.js';
-/**
- * K8s-specific additions to the common lease settings.  When `apiServerUrl`,
- * `authToken`, or `caCert` are omitted the adapter probes the standard
- * ServiceAccount mount points (`/var/run/secrets/kubernetes.io/...`).
- *
- * `client` is a test seam — pass a fake `K8sFetchClient` to drive the
- * lease without a real API server.
- */
-export interface KubernetesLeaseSettings extends LeaseSettings {
-    /** Kubernetes namespace that owns the `coordination.k8s.io/v1/Lease` object. */
-    readonly namespace: string;
-    /** API-server URL.  Defaults to the in-cluster service or `https://kubernetes.default.svc`. */
-    readonly apiServerUrl?: string;
-    /** Bearer token for the ServiceAccount.  Reads `/var/run/...` if omitted. */
-    readonly authToken?: string;
-    /** PEM-encoded CA cert for the API server.  Reads `/var/run/...` if omitted. */
-    readonly caCert?: string;
-    /** Test seam — inject a fake fetch client. */
-    readonly client?: K8sFetchClient;
-}
+import type { Lease } from '../Lease.js';
+import type { KubernetesLeaseOptions } from './KubernetesLeaseOptions.js';
 /**
  * Lease backed by a Kubernetes `coordination.k8s.io/v1/Lease` object.
  * Self-contained — speaks the K8s REST API directly, no client-library
@@ -30,7 +10,7 @@ export interface KubernetesLeaseSettings extends LeaseSettings {
  * Lifecycle:
  *
  *   1. **acquire()** — GET the lease object.  If it doesn't exist, CREATE
- *      it with `holderIdentity = settings.owner`.  If it does exist and
+ *      it with `holderIdentity = options.owner`.  If it does exist and
  *      either it's already ours or the previous holder's `renewTime + ttl`
  *      has passed, PUT a new spec with our owner + a fresh
  *      `acquireTime` / `renewTime`.  Returns true on success, false on a
@@ -53,17 +33,32 @@ export interface KubernetesLeaseSettings extends LeaseSettings {
  *   - The K8s API server is unreachable for longer than `ttlMs`.
  */
 export declare class KubernetesLease implements Lease {
-    private readonly settings;
     private readonly renewalIntervalMs;
     private renewalTimer;
     private held;
     private currentLease;
     private readonly onLostHandlers;
     private creds;
-    constructor(settings: KubernetesLeaseSettings);
+    private readonly options;
+    constructor(options?: KubernetesLeaseOptions);
     /** Resolve credentials lazily — once on first call, cached after. */
     private getCreds;
     acquire(): Promise<boolean>;
+    /**
+     * Fencing-token variant: returns a backend-issued token assembled
+     * from the K8s `Lease` object's `metadata.resourceVersion` and the
+     * `spec.leaseTransitions` counter — both monotonically bumped by
+     * the API server on every successful PUT.  The combination is
+     * unique per acquire across the lease's lifetime, so a
+     * late-arriving "I acquired" can be distinguished from a fresh
+     * one by its token.
+     *
+     * Format: `<resourceVersion>/<leaseTransitions>` (resourceVersion
+     * is opaque K8s state; leaseTransitions is decimal).
+     */
+    acquireWithToken(): Promise<{
+        readonly token: string;
+    } | null>;
     /** One pass of GET → CREATE-or-PUT.  Three outcomes: success / held-by-other / race. */
     private tryAcquireOnce;
     /** True iff the existing lease has a different live holder. */

package/dist/coordination/leases/KubernetesLease.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"KubernetesLease.d.ts","sourceRoot":"","sources":["../../../src/coordination/leases/KubernetesLease.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAQL,KAAK,cAAc,EAEpB,MAAM,aAAa,CAAC;AAErB;;;;;;;GAOG;AACH,MAAM,WAAW,uBAAwB,SAAQ,aAAa;IAC5D,gFAAgF;IAChF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,+FAA+F;IAC/F,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,6EAA6E;IAC7E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,gFAAgF;IAChF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,8CAA8C;IAC9C,QAAQ,CAAC,MAAM,CAAC,EAAE,cAAc,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,qBAAa,eAAgB,YAAW,KAAK;IAQ/B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAPrC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,YAAY,CAA+C;IACnE,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,YAAY,CAA+B;IACnD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAuC;IACtE,OAAO,CAAC,KAAK,CAA+B;gBAEf,QAAQ,EAAE,uBAAuB;IAK9D,qEAAqE;YACvD,QAAQ;IA2BhB,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC;IAcjC,wFAAwF;YAC1E,cAAc;IAkD5B,+DAA+D;IAC/D,OAAO,CAAC,kBAAkB;IAWpB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAmB9B,UAAU,IAAI,OAAO;IAErB,MAAM,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI;IAOrD,OAAO,CAAC,gBAAgB;YAOV,SAAS;IAmCvB,OAAO,CAAC,QAAQ;CAYjB"}
+{"version":3,"file":"KubernetesLease.d.ts","sourceRoot":"","sources":["../../../src/coordination/leases/KubernetesLease.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,KAAK,EAAE,sBAAsB,EAA8B,MAAM,6BAA6B,CAAC;AAYtG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,qBAAa,eAAgB,YAAW,KAAK;IAC3C,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,YAAY,CAA+C;IACnE,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,YAAY,CAA+B;IACnD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAuC;IACtE,OAAO,CAAC,KAAK,CAA+B;IAE5C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA6B;gBAEzC,OAAO,GAAE,sBAA2B;IAOhD,qEAAqE;YACvD,QAAQ;IA2BhB,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC;IAIjC;;;;;;;;;;;OAWG;IACG,gBAAgB,IAAI,OAAO,CAAC;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAmBpE,wFAAwF;YAC1E,cAAc;IAkD5B,+DAA+D;IAC/D,OAAO,CAAC,kBAAkB;IAWpB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAmB9B,UAAU,IAAI,OAAO;IAErB,MAAM,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI;IAOrD,OAAO,CAAC,gBAAgB;YAOV,SAAS;IAmCvB,OAAO,CAAC,QAAQ;CAYjB"}

package/dist/coordination/leases/KubernetesLease.js

@@ -1,3 +1,4 @@
+import { KubernetesLeaseOptionsValidator } from './KubernetesLeaseOptions.js';
 import { createLease, deleteLease, getLease, K8sLeaseError, loadInClusterCredentials, updateLease, } from './k8sApi.js';
 /**
  * Lease backed by a Kubernetes `coordination.k8s.io/v1/Lease` object.
@@ -9,7 +10,7 @@ import { createLease, deleteLease, getLease, K8sLeaseError, loadInClusterCredent
  * Lifecycle:
  *
  *   1. **acquire()** — GET the lease object.  If it doesn't exist, CREATE
- *      it with `holderIdentity = settings.owner`.  If it does exist and
+ *      it with `holderIdentity = options.owner`.  If it does exist and
  *      either it's already ours or the previous holder's `renewTime + ttl`
  *      has passed, PUT a new spec with our owner + a fresh
  *      `acquireTime` / `renewTime`.  Returns true on success, false on a
@@ -32,27 +33,28 @@ import { createLease, deleteLease, getLease, K8sLeaseError, loadInClusterCredent
  *   - The K8s API server is unreachable for longer than `ttlMs`.
  */
 export class KubernetesLease {
-    settings;
     renewalIntervalMs;
     renewalTimer = null;
     held = false;
     currentLease = null;
     onLostHandlers = new Set();
     creds = null;
-    constructor(settings) {
-        this.settings = settings;
-        this.renewalIntervalMs = settings.renewalIntervalMs
-            ?? Math.max(500, Math.floor(settings.ttlMs / 3));
+    options;
+    constructor(options = {}) {
+        this.options = options;
+        new KubernetesLeaseOptionsValidator().validate(this.options);
+        this.renewalIntervalMs = this.options.renewalIntervalMs
+            ?? Math.max(500, Math.floor(this.options.ttlMs / 3));
     }
     /** Resolve credentials lazily — once on first call, cached after. */
     async getCreds() {
         if (this.creds)
             return this.creds;
-        if (this.settings.apiServerUrl && this.settings.authToken && this.settings.caCert) {
+        if (this.options.apiServerUrl && this.options.authToken && this.options.caCert) {
             this.creds = {
-                apiServerUrl: this.settings.apiServerUrl,
-                authToken: this.settings.authToken,
-                caCert: this.settings.caCert,
+                apiServerUrl: this.options.apiServerUrl,
+                authToken: this.options.authToken,
+                caCert: this.options.caCert,
             };
             return this.creds;
         }
@@ -63,45 +65,64 @@ export class KubernetesLease {
                 + `(${'/var/run/secrets/kubernetes.io/serviceaccount'}).`);
         }
         this.creds = {
-            apiServerUrl: this.settings.apiServerUrl ?? inCluster.apiServerUrl,
-            authToken: this.settings.authToken ?? inCluster.authToken,
-            caCert: this.settings.caCert ?? inCluster.caCert,
+            apiServerUrl: this.options.apiServerUrl ?? inCluster.apiServerUrl,
+            authToken: this.options.authToken ?? inCluster.authToken,
+            caCert: this.options.caCert ?? inCluster.caCert,
             defaultNamespace: inCluster.defaultNamespace,
         };
         return this.creds;
     }
     async acquire() {
-        const retries = this.settings.acquireRetries ?? 3;
-        const retryDelay = this.settings.acquireRetryDelayMs ?? 100;
+        return (await this.acquireWithToken()) !== null;
+    }
+    /**
+     * Fencing-token variant: returns a backend-issued token assembled
+     * from the K8s `Lease` object's `metadata.resourceVersion` and the
+     * `spec.leaseTransitions` counter — both monotonically bumped by
+     * the API server on every successful PUT.  The combination is
+     * unique per acquire across the lease's lifetime, so a
+     * late-arriving "I acquired" can be distinguished from a fresh
+     * one by its token.
+     *
+     * Format: `<resourceVersion>/<leaseTransitions>` (resourceVersion
+     * is opaque K8s state; leaseTransitions is decimal).
+     */
+    async acquireWithToken() {
+        const retries = this.options.acquireRetries ?? 3;
+        const retryDelay = this.options.acquireRetryDelayMs ?? 100;
         for (let attempt = 0; attempt < retries; attempt++) {
             const result = await this.tryAcquireOnce();
-            if (result === 'success')
-                return true;
+            if (result === 'success') {
+                const obj = this.currentLease;
+                const rv = obj?.metadata?.resourceVersion ?? 'unknown';
+                const transitions = obj?.spec.leaseTransitions ?? 0;
+                return { token: `${rv}/${transitions}` };
+            }
             if (result === 'held-by-other')
-                return false;
+                return null;
             // 'race' — someone else mutated the lease between our GET and PUT;
             // back off briefly and retry.
             if (attempt < retries - 1)
                 await sleep(retryDelay);
         }
-        return false;
+        return null;
     }
     /** One pass of GET → CREATE-or-PUT.  Three outcomes: success / held-by-other / race. */
     async tryAcquireOnce() {
         const creds = await this.getCreds();
-        const ns = this.settings.namespace;
-        const name = this.settings.name;
-        const ttlSec = Math.max(1, Math.ceil(this.settings.ttlMs / 1000));
+        const ns = this.options.namespace;
+        const name = this.options.name;
+        const ttlSec = Math.max(1, Math.ceil(this.options.ttlMs / 1000));
         const now = new Date().toISOString();
-        const existing = await getLease(creds, ns, name, this.settings.client);
+        const existing = await getLease(creds, ns, name, this.options.client);
         if (existing === null) {
             // No lease object yet — create.  CREATE returns null on 409 (race lost).
             const created = await createLease(creds, ns, {
-                holderIdentity: this.settings.owner,
+                holderIdentity: this.options.owner,
                 leaseDurationSeconds: ttlSec,
                 acquireTime: now,
                 renewTime: now,
-            }, name, this.settings.client);
+            }, name, this.options.client);
             if (!created)
                 return 'race';
             this.held = true;
@@ -115,19 +136,19 @@ export class KubernetesLease {
         // Either ours or expired — bump owner via PUT with the resourceVersion
         // we just GET'd.  K8s rejects with 409 if anyone else mutated since.
         const transitionsBefore = existing.spec.leaseTransitions ?? 0;
-        const ownerChanging = existing.spec.holderIdentity !== this.settings.owner;
+        const ownerChanging = existing.spec.holderIdentity !== this.options.owner;
         const updated = {
             ...existing,
             spec: {
                 ...existing.spec,
-                holderIdentity: this.settings.owner,
+                holderIdentity: this.options.owner,
                 leaseDurationSeconds: ttlSec,
                 acquireTime: now,
                 renewTime: now,
                 leaseTransitions: ownerChanging ? transitionsBefore + 1 : transitionsBefore,
             },
         };
-        const result = await updateLease(creds, updated, this.settings.client);
+        const result = await updateLease(creds, updated, this.options.client);
         if (!result)
             return 'race';
         this.held = true;
@@ -140,10 +161,10 @@ export class KubernetesLease {
         const holder = lease.spec.holderIdentity;
         if (!holder)
             return false; // unowned
-        if (holder === this.settings.owner)
+        if (holder === this.options.owner)
             return false; // we already hold it
         const renewTime = lease.spec.renewTime;
-        const durationSec = lease.spec.leaseDurationSeconds ?? this.settings.ttlMs / 1000;
+        const durationSec = lease.spec.leaseDurationSeconds ?? this.options.ttlMs / 1000;
         if (!renewTime)
             return true; // owned but no time → assume live
         const expiresAt = new Date(renewTime).getTime() + durationSec * 1000;
@@ -161,7 +182,7 @@ export class KubernetesLease {
         if (!creds)
             return;
         try {
-            await deleteLease(creds, this.settings.namespace, this.settings.name, this.settings.client);
+            await deleteLease(creds, this.options.namespace, this.options.name, this.options.client);
         }
         catch (e) {
             // best-effort — log via thrown info but don't fail the caller
@@ -195,18 +216,18 @@ export class KubernetesLease {
             return;
         }
         const now = new Date().toISOString();
-        const ttlSec = Math.max(1, Math.ceil(this.settings.ttlMs / 1000));
+        const ttlSec = Math.max(1, Math.ceil(this.options.ttlMs / 1000));
         const updated = {
             ...this.currentLease,
             spec: {
                 ...this.currentLease.spec,
-                holderIdentity: this.settings.owner,
+                holderIdentity: this.options.owner,
                 leaseDurationSeconds: ttlSec,
                 renewTime: now,
             },
         };
         try {
-            const result = await updateLease(creds, updated, this.settings.client);
+            const result = await updateLease(creds, updated, this.options.client);
             if (!result) {
                 // 409 / 404 — somebody else won, or the object was deleted.
                 this.fireLost('lease lost during renewal (conflict or 404)');
@@ -230,9 +251,9 @@ export class KubernetesLease {
             this.renewalTimer = null;
         }
         this.currentLease = null;
-        for (const h of this.onLostHandlers) {
+        for (const handler of this.onLostHandlers) {
             try {
-                h(reason);
+                handler(reason);
             }
             catch { /* swallow */ }
         }