@hashgraph/solo/dist/src/core/lock/interval-lock.d.ts

An opinionated CLI tool to deploy and manage private Hedera Networks.

import { type K8Factory } from '../../integration/kube/k8-factory.js';
import { LockHolder } from './lock-holder.js';
import { type Lock, type LockRenewalService } from './lock.js';
import { type NamespaceName } from '../../types/namespace/namespace-name.js';
/**
 * Concrete implementation of a Kubernetes time-based mutually exclusive lock via the Coordination API.
 * Applies a namespace/deployment wide lock to ensure that only one process, machine, and user can hold the lock at a time.
 * The lock is automatically renewed in the background to prevent expiration and ensure the holder maintains the lock.
 * If the process die, the lock is automatically released after the lock duration.
 *
 * @public
 */
export declare class IntervalLock implements Lock {
    readonly k8Factory: K8Factory;
    readonly renewalService: LockRenewalService;
    /** The holder of the lock. */
    private readonly _lockHolder;
    /** The namespace which contains the lease. */
    private readonly _namespace;
    /** The name of the lease. */
    private readonly _leaseName;
    /** The duration in seconds for which the lease is to be held. */
    private readonly _durationSeconds;
    /** The identifier of the scheduled lease renewal. */
    private _scheduleId;
    /**
     * @param k8Factory - Injected kubernetes K8Factory need by the methods to create, renew, and delete leases.
     * @param renewalService - Injected lock renewal service need to support automatic (background) lock renewals.
     * @param lockHolder - The holder of the lock.
     * @param namespace - The namespace in which the lease is to be acquired.
     * @param leaseName - The name of the lease to be acquired; if not provided, the namespace is used.
     * @param durationSeconds - The duration in seconds for which the lock is to be held; if not provided, the default value is used.
     */
    constructor(k8Factory: K8Factory, renewalService: LockRenewalService, lockHolder: LockHolder, namespace: NamespaceName, leaseName?: string | null, durationSeconds?: number | null);
    /**
     * The name of the lease.
     */
    get leaseName(): string;
    /**
     * The holder of the lock.
     */
    get lockHolder(): LockHolder;
    /**
     * The namespace in which the lease is to be acquired. By default, the namespace is used as the lease name.
     * The defaults assume there is only a single deployment in a given namespace.
     */
    get namespace(): NamespaceName;
    /**
     * The duration in seconds for which the lease is held before being considered expired. By default, the duration
     * is set to 20 seconds. It is recommended to renew the lease at 50% of the duration to prevent unexpected expiration.
     */
    get durationSeconds(): number;
    /**
     * The identifier of the scheduled lease renewal task.
     */
    get scheduleId(): number | null;
    /**
     * Internal setter for the scheduleId property. External callers should not use this method.
     *
     * @param scheduleId - The identifier of the scheduled lease renewal task.
     */
    private set scheduleId(value);
    /**
     * Acquires the lock. If the lock is already acquired, it checks if the lock is expired or held by the same process.
     * If the lock is expired, it creates a new lock. If the lock is held by the same process, it renews the lock.
     * If the lock is held by another process, then an exception is thrown.
     *
     * @throws LockAcquisitionError - If the lock is already acquired by another process or an error occurs during acquisition.
     */
    acquire(): Promise<void>;
    /**
     * Attempts to acquire the lock, by calling the acquire method. If an exception is thrown, it is caught and false is returned.
     * If the lock is successfully acquired, true is returned; otherwise, false is returned.
     *
     * @returns true if the lock is successfully acquired; otherwise, false.
     */
    tryAcquire(): Promise<boolean>;
    /**
     * Renews the lock. If the lock is expired or held by the same process, it creates or renews the lock.
     * If the lock is held by another process, then an exception is thrown.
     *
     * @throws LockAcquisitionError - If the lock is already acquired by another process or an error occurs during renewal.
     */
    renew(): Promise<void>;
    /**
     * Attempts to renew the lock, by calling the renew method. If an exception is thrown, it is caught and false is returned.
     * If the lock is successfully renewed, true is returned; otherwise, false is returned.
     *
     * @returns true if the lock is successfully renewed; otherwise, false.
     */
    tryRenew(): Promise<boolean>;
    /**
     * Releases the lock. If the lock is expired or held by the same process, it deletes the lock.
     * If the lock is held by another process, then an exception is thrown.
     *
     * @param immediate - If true, the safe sleep period is skipped
     * @throws LockRelinquishmentError - If the lock is already acquired by another process or an error occurs during relinquishment.
     */
    release(immediate?: boolean): Promise<void>;
    /**
     * Attempts to release the lock, by calling the release method. If an exception is thrown, it is caught and false is returned.
     * If the lock is successfully released, true is returned; otherwise, false is returned.
     *
     * @returns true if the lock is successfully released; otherwise, false.
     */
    tryRelease(): Promise<boolean>;
    /**
     * Checks if the lock is acquired. If the lock is acquired and not expired, it returns true; otherwise, false.
     *
     * @returns true if the lock is acquired and not expired; otherwise, false.
     */
    isAcquired(): Promise<boolean>;
    /**
     * Checks if the lock is expired. If the lock is expired, it returns true; otherwise, false.
     * This method does not verify if the lock is acquired by the current process.
     *
     * @returns true if the lock is expired; otherwise, false.
     */
    isExpired(): Promise<boolean>;
    /**
     * Retrieves the lease from the Kubernetes API server.
     *
     * @returns the Kubernetes lease object if it exists; otherwise, null.
     * @throws LockAcquisitionError - If an error occurs during retrieval.
     */
    private retrieveLease;
    /**
     * Creates or renews the lease. If the lease does not exist, it creates a new lease. If the lease exists, it renews the lease.
     *
     * @param lease - The lease to be created or renewed.
     */
    private createOrRenewLease;
    /**
     * Determines if a renew conflict can be safely ignored.
     *
     * @param error - the renew error to evaluate.
     * @returns true if the conflict should be ignored; otherwise, false.
     */
    private shouldIgnoreRenewConflict;
    /**
     * Determines whether an error or any nested cause contains the specified status code.
     *
     * @param error - the error to inspect.
     * @param statusCode - the status code to match.
     * @returns true if the status code is found in the error chain; otherwise, false.
     */
    private static hasStatusCode;
    /**
     * Transfers an existing (expired) lease to the current process.
     *
     * @param lease - The lease to be transferred.
     */
    private transferLease;
    /**
     * Deletes the lease from the Kubernetes API server.
     */
    private deleteLease;
    /**
     * Determines if the lease has expired by comparing the delta in seconds between the current time and the last renewal time.
     *
     * @param lease - The lease to be checked for expiration.
     * @returns true if the lease has expired; otherwise, false.
     */
    private static checkExpiration;
    /**
     * Determines if the lock is held by the same process. This comparison is based on the user, machine, and
     * process identifier of the leaseholder.
     *
     * @param lease - The lease to be checked for ownership.
     * @returns true if the lease is held by the same process; otherwise, false.
     */
    private heldBySameProcess;
    /**
     * Determines if the lock is held by the same machine identity. This comparison is based on the user and machine only.
     * The process identifier is not considered in this comparison.
     *
     * @param lease - The lease to be checked for ownership.
     * @returns true if the lease is held by the same user and machine; otherwise, false.
     */
    private heldBySameMachineIdentity;
}