@lossless.org/objectstorage 10.7.1 → 11.1.0

package/dist_ts/dashboard.interfaces.d.ts

@@ -0,0 +1,132 @@
+import type { ITypedRequest, implementsTR } from '@api.global/typedrequest-interfaces';
+import type { ITypedSocketEvent } from '@api.global/typedsocket';
+/**
+ * Engine snapshot shapes, as `ObjectStorage.getClusterSnapshot()` returns
+ * them. The engine builds them from memory only: the drive states the last
+ * heartbeat probe left, runtime stats, healing state, S3 listener counters
+ * and a bounded ring of recent events. Times are milliseconds since the Unix
+ * epoch; absent values are `null`.
+ */
+export interface IObjectStorageTelemetryEvent {
+    /** Numbered per node from 1; a gap means older events left the ring. */
+    seq: number;
+    at: number;
+    kind: 'engine' | 'peer' | 'drive' | 'healing';
+    severity: 'info' | 'warning' | 'error';
+    message: string;
+}
+/** S3 listener counters since the engine started; bytes include HTTP headers. */
+export interface IObjectStorageTrafficCounters {
+    requestsTotal: number;
+    errorResponses: number;
+    bytesIn: number;
+    bytesOut: number;
+}
+export interface IObjectStorageStorageTotals {
+    bucketCount: number;
+    objectCount: number;
+    totalBytes: number;
+}
+export interface IObjectStorageDriveSnapshot {
+    index: number;
+    path: string;
+    status: 'online' | 'degraded' | 'offline' | 'healing';
+    totalBytes: number;
+    usedBytes: number;
+    availableBytes: number;
+    errorCount: number;
+    lastError: string | null;
+    lastCheck: number | null;
+    erasureSetId: number | null;
+}
+export interface IObjectStorageHealingSnapshot {
+    active: boolean;
+    scanIntervalMs: number;
+    lastRunStartedAt: number | null;
+    lastRunCompletedAt: number | null;
+    lastDurationMs: number | null;
+    shardsChecked: number | null;
+    shardsHealed: number | null;
+    shardsPending: number | null;
+    failed: number | null;
+    lastError: string | null;
+}
+/** What one node reports about itself; local and remote nodes share this shape. */
+export interface IObjectStorageNodeSnapshot {
+    /** Absent in standalone mode. */
+    nodeId: string | null;
+    mode: 'standalone' | 'cluster';
+    startedAt: number;
+    capturedAt: number;
+    traffic: IObjectStorageTrafficCounters;
+    storage: IObjectStorageStorageTotals;
+    /** Local drives (cluster mode); empty in standalone mode. */
+    drives: IObjectStorageDriveSnapshot[];
+    healing: IObjectStorageHealingSnapshot | null;
+    /** Recent events, oldest first. */
+    events: IObjectStorageTelemetryEvent[];
+}
+export interface IObjectStoragePeerSnapshot {
+    nodeId: string;
+    status: 'online' | 'suspect' | 'offline';
+    quicAddress: string;
+    s3Address: string;
+    driveCount: number;
+    lastHeartbeat: number;
+    missedHeartbeats: number;
+    /** The peer's own snapshot, when it answered within a second. */
+    snapshot: IObjectStorageNodeSnapshot | null;
+    unavailableReason: string | null;
+}
+export interface IObjectStorageErasureSnapshot {
+    dataShards: number;
+    parityShards: number;
+    chunkSizeBytes: number;
+    totalShards: number;
+    readQuorum: number;
+    writeQuorum: number;
+    erasureSetCount: number;
+}
+export interface IObjectStorageClusterViewSnapshot {
+    nodeId: string;
+    quorumHealthy: boolean;
+    majorityHealthy: boolean;
+    erasure: IObjectStorageErasureSnapshot;
+    peers: IObjectStoragePeerSnapshot[];
+}
+export interface IObjectStorageClusterSnapshot {
+    capturedAt: number;
+    clusterEnabled: boolean;
+    local: IObjectStorageNodeSnapshot;
+    /** Absent in standalone mode. */
+    cluster: IObjectStorageClusterViewSnapshot | null;
+}
+/**
+ * Dashboard configuration. The dashboard is off unless `enabled` is true.
+ */
+export interface IObjectStorageDashboardConfig {
+    enabled: boolean;
+    /** Interface the dashboard listens on. Default `127.0.0.1`. */
+    address?: string;
+    /** TCP port; `0` asks the OS for one. Default 3001; must differ from the S3 port. */
+    port?: number;
+}
+/** One dashboard sample, as pushed to every connected dashboard. */
+export interface IObjectStorageDashboardSample {
+    sampledAt: number;
+    /** The snapshot, or `null` when the engine could not answer. */
+    snapshot: IObjectStorageClusterSnapshot | null;
+    error: string | null;
+    /** Events were left out of peer snapshots to keep the sample within the push limit. */
+    eventsTruncated: boolean;
+}
+/** Answers with the latest sample, taking one when none exists yet. */
+export interface IReq_ObjectStorageDashboardGetSample extends implementsTR<ITypedRequest, IReq_ObjectStorageDashboardGetSample> {
+    method: 'objectStorageDashboardGetSample';
+    request: Record<string, never>;
+    response: IObjectStorageDashboardSample;
+}
+/** Pushed every two seconds while at least one dashboard is connected. */
+export interface IEvent_ObjectStorageDashboardSample extends ITypedSocketEvent<IObjectStorageDashboardSample> {
+    name: 'objectStorageDashboardSample';
+}

package/dist_ts/dashboard.interfaces.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZGFzaGJvYXJkLmludGVyZmFjZXMuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90cy9kYXNoYm9hcmQuaW50ZXJmYWNlcy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiIn0=

package/dist_ts/dashboard.plugins.d.ts

@@ -0,0 +1,5 @@
+import * as typedrequest from '@api.global/typedrequest';
+import * as typedsocket from '@api.global/typedsocket';
+export { typedrequest, typedsocket };
+import * as smartserve from '@push.rocks/smartserve';
+export { smartserve };

package/dist_ts/dashboard.plugins.js

@@ -0,0 +1,10 @@
+// Loaded only by the dashboard module, which `ObjectStorage` imports
+// dynamically when the dashboard is enabled.
+// @api.global scope
+import * as typedrequest from '@api.global/typedrequest';
+import * as typedsocket from '@api.global/typedsocket';
+export { typedrequest, typedsocket };
+// @push.rocks scope
+import * as smartserve from '@push.rocks/smartserve';
+export { smartserve };
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZGFzaGJvYXJkLnBsdWdpbnMuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90cy9kYXNoYm9hcmQucGx1Z2lucy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxxRUFBcUU7QUFDckUsNkNBQTZDO0FBRTdDLG9CQUFvQjtBQUNwQixPQUFPLEtBQUssWUFBWSxNQUFNLDBCQUEwQixDQUFDO0FBQ3pELE9BQU8sS0FBSyxXQUFXLE1BQU0seUJBQXlCLENBQUM7QUFFdkQsT0FBTyxFQUFFLFlBQVksRUFBRSxXQUFXLEVBQUUsQ0FBQztBQUVyQyxvQkFBb0I7QUFDcEIsT0FBTyxLQUFLLFVBQVUsTUFBTSx3QkFBd0IsQ0FBQztBQUVyRCxPQUFPLEVBQUUsVUFBVSxFQUFFLENBQUMifQ==

package/dist_ts/index.d.ts

@@ -1,4 +1,6 @@
 import * as plugins from './plugins.js';
+import type { IObjectStorageClusterSnapshot, IObjectStorageDashboardConfig } from './dashboard.interfaces.js';
+export * from './dashboard.interfaces.js';
 /**
  * Authentication configuration
  */
@@ -54,6 +56,11 @@ export interface ILimitsConfig {
 export interface IMultipartConfig {
     expirationDays?: number;
     cleanupIntervalMinutes?: number;
+    /**
+     * Open multipart uploads that the prefix credentials of one scope (bucket
+     * and prefix) may hold together (default 100). Counted in memory.
+     */
+    maxUploadsPerPrefixScope?: number;
 }
 /**
  * Server configuration
@@ -100,6 +107,11 @@ export interface IStorageConfig {
 export interface IErasureConfig {
     dataShards?: number;
     parityShards?: number;
+    /**
+     * Bytes per erasure-coded chunk, between 1 and 64 MiB (67,108,864 bytes);
+     * startup refuses a value outside that range, because every manifest
+     * refuses a larger chunk. Default 4,194,304 (4 MiB).
+     */
     chunkSizeBytes?: number;
 }
 /**
@@ -107,12 +119,41 @@ export interface IErasureConfig {
  */
 export interface IDriveConfig {
     paths: string[];
+    /**
+     * Accept drive roots that share a device (`st_dev`). Each drive root counts
+     * as one failure domain, so by default startup refuses two drive roots on
+     * one device. Set this only for dev and test clusters whose drive roots are
+     * directories on one filesystem. Default false.
+     */
+    allowSharedDevice?: boolean;
+}
+/**
+ * Mutual TLS for the cluster transport. Every file is read once at startup and
+ * must lie outside the control and drive roots, at an absolute path without
+ * symbolic links; a restart reloads them.
+ */
+export interface IClusterTlsConfig {
+    /** PEM file with one or two CA certificates (two only during a CA rotation). */
+    caFile: string;
+    /**
+     * PEM file with this node's certificate, optionally followed by intermediates. It has one DNS SAN,
+     * equal to nodeId, and is valid for server and client authentication: an extended key usage
+     * extension listing serverAuth and clientAuth, or no extended key usage extension.
+     */
+    certFile: string;
+    /** PEM private key of certFile; owned by the engine's user, mode 0600 or 0400. */
+    keyFile: string;
 }
 /**
  * Cluster configuration for distributed mode
  */
 export interface IClusterConfig {
     enabled: boolean;
+    /**
+     * This node's id. Generated and persisted when omitted, except with `tls`:
+     * then it is required and must be a lowercase DNS name equal to the node
+     * certificate's DNS subject alternative name.
+     */
     nodeId?: string;
     quicPort?: number;
     seedNodes?: string[];
@@ -120,11 +161,27 @@ export interface IClusterConfig {
     drives?: IDriveConfig;
     heartbeatIntervalMs?: number;
     heartbeatTimeoutMs?: number;
+    /**
+     * Longest a single GET may run, in milliseconds, from its start to its last
+     * byte, including the client's transfer time. A longer GET is aborted.
+     * Superseded and deleted object generations keep their shards for this
+     * deadline plus the smaller of the deadline and one hour, then cleanup frees
+     * them. Must be the same on every node: a mismatch can abort streams but
+     * never serves wrong bytes. Default 21,600,000 (6 hours); allowed from
+     * 60,000 (1 minute) to 604,800,000 (7 days).
+     */
+    getDeadlineMs?: number;
+    /**
+     * Mutual TLS for the cluster transport. Without it the transport is
+     * encrypted but authenticates no peer. Every node of a cluster sets it, or
+     * none does: enabling it is a full stop of every node, not a rolling change.
+     */
+    tls?: IClusterTlsConfig;
 }
 /**
  * Configuration as the engine receives it: every section resolved.
  */
-export type TObjectStorageResolvedConfig = Required<Omit<IObjectStorageConfig, 'binaryPath'>>;
+export type TObjectStorageResolvedConfig = Required<Omit<IObjectStorageConfig, 'binaryPath' | 'dashboard'>>;
 /**
  * Complete objectstorage configuration
  */
@@ -144,6 +201,11 @@ export interface IObjectStorageConfig {
     limits?: ILimitsConfig;
     multipart?: IMultipartConfig;
     cluster?: IClusterConfig;
+    /**
+     * The read-only visibility dashboard, served by this process on its own
+     * port. Off unless `enabled` is true; never sent to the engine.
+     */
+    dashboard?: IObjectStorageDashboardConfig;
 }
 /**
  * Logical bucket stats maintained by the Rust runtime.
@@ -281,6 +343,32 @@ export interface IBucketTenantMetadata {
     region?: string;
     retention?: IBucketRetentionReceipt;
 }
+export interface IPrefixCredentialInput {
+    bucketName: string;
+    /** Unreserved characters (RFC 3986) and `/`; ends with `/`, no leading `/`. */
+    prefix: string;
+    /** First node: lifetime in seconds, 1..43200. */
+    ttlSeconds?: number;
+    /** Fan-out to further nodes: the first node's expiresAt (epoch ms). */
+    expiresAt?: number;
+    /** Supply both together with expiresAt to install an existing credential on another node. */
+    accessKeyId?: string;
+    secretAccessKey?: string;
+    region?: string;
+}
+export interface IPrefixCredentialMetadata {
+    accessKeyId: string;
+    bucketName: string;
+    prefix: string;
+    region: string;
+    /** Epoch ms. */
+    createdAt: number;
+    /** Epoch ms; requests are refused from this instant and admitted ones end at it. */
+    expiresAt: number;
+}
+export interface IPrefixCredential extends IPrefixCredentialMetadata {
+    secretAccessKey: string;
+}
 export interface IBucketRetentionPolicyInput {
     mode: 'compliance';
     policyId: string;
@@ -622,6 +710,10 @@ export interface IObjectStorageHealth {
         enabled: boolean;
         credentialCount: number;
         tenantCredentialCount: number;
+        prefixCredentialCount: number;
+        prefixCredentialTombstoneCount: number;
+        /** False when the prefix credential file is unreadable: every prefix credential is refused. */
+        prefixCredentialStoreAvailable: boolean;
     };
     bucketCount: number;
     objectCount: number;
@@ -641,6 +733,12 @@ export declare class ObjectStorageResourceFenceError extends Error {
     readonly code: TObjectStorageResourceFenceErrorCode;
     constructor(codeArg: TObjectStorageResourceFenceErrorCode, messageArg: string, causeArg?: unknown);
 }
+export declare const objectStorageCredentialErrorCodes: readonly ['ECREDENTIAL_AUTH_DISABLED', 'ECREDENTIAL_INVALID_PREFIX', 'ECREDENTIAL_INVALID_TTL', 'ECREDENTIAL_INVALID_EXPIRY', 'ECREDENTIAL_INVALID_KEY', 'ECREDENTIAL_NO_SUCH_BUCKET', 'ECREDENTIAL_BUCKET_UNAVAILABLE', 'ECREDENTIAL_CONFLICT', 'ECREDENTIAL_REVOKED', 'ECREDENTIAL_NOT_PREFIX', 'ECREDENTIAL_LIMIT', 'ECREDENTIAL_PERSISTENCE', 'ECREDENTIAL_STORE_UNAVAILABLE'];
+export type TObjectStorageCredentialErrorCode = (typeof objectStorageCredentialErrorCodes)[number];
+export declare class ObjectStorageCredentialError extends Error {
+    readonly code: TObjectStorageCredentialErrorCode;
+    constructor(codeArg: TObjectStorageCredentialErrorCode, messageArg: string, causeArg?: unknown);
+}
 export interface IObjectStorageMetrics {
     bucketCount: number;
     objectCount: number;
@@ -662,6 +760,33 @@ export interface IClusterPeerHealth {
     lastHeartbeat?: number;
     missedHeartbeats?: number;
 }
+/**
+ * A drive's medium: `'rotational'` and `'flash'` (network volumes included),
+ * `'smr'` for drive-managed SMR, which reports itself as rotational and is
+ * never detected, and `'zoned'` for host-managed or host-aware SMR and ZNS.
+ */
+export type TDriveMedia = 'rotational' | 'smr' | 'flash' | 'zoned';
+/**
+ * A drive's media.
+ */
+export interface IClusterDriveMedia {
+    /**
+     * The media the configuration declares for the drive. Not reported yet:
+     * drives cannot declare their media.
+     */
+    declared?: TDriveMedia;
+    /**
+     * What the engine detected once at startup, from the whole disk behind the
+     * drive root's filesystem (Linux sysfs `queue/zoned` and `queue/rotational`;
+     * a partition counts as its disk). `'unknown'` for filesystems without a
+     * block device of their own (tmpfs, overlay, network filesystems),
+     * device-mapper, md, loop and other virtual block devices, and on every
+     * platform but Linux. Virtual and network block devices report the
+     * rotational flag their driver or hypervisor sets (QEMU disks show
+     * `'rotational'` unless configured with `rotation_rate=1`).
+     */
+    detected: TDriveMedia | 'unknown';
+}
 /**
  * Local drive health as measured by objectstorage's runtime probes.
  */
@@ -676,6 +801,7 @@ export interface IClusterDriveHealth {
     lastError?: string;
     lastCheck?: number;
     erasureSetId?: number;
+    media: IClusterDriveMedia;
 }
 export interface IClusterErasureHealth {
     dataShards: number;
@@ -694,9 +820,28 @@ export interface IClusterRepairHealth {
     lastDurationMs?: number;
     shardsChecked?: number;
     shardsHealed?: number;
+    /** Pending shards (writes that failed at publication) the last scan left pending. */
+    shardsPending?: number;
     failed?: number;
     lastError?: string;
 }
+export interface IClusterTransportCertificate {
+    /** SHA-256 of the DER certificate, lowercase hex. */
+    sha256: string;
+    /** Milliseconds since the Unix epoch. */
+    notAfter: number;
+}
+/**
+ * How the cluster transport authenticates peers, and the certificates it
+ * loaded at startup.
+ */
+export interface IClusterTransportHealth {
+    mode: 'mutualTls' | 'unauthenticated';
+    /** This node's certificate; only in mode 'mutualTls'. */
+    certificate?: IClusterTransportCertificate;
+    /** The loaded CA bundle in file order; only in mode 'mutualTls'. */
+    caCertificates?: IClusterTransportCertificate[];
+}
 /**
  * Cluster runtime health from the Rust core.
  * When clustering is disabled, the response is `{ enabled: false }`.
@@ -712,6 +857,34 @@ export interface IClusterHealth {
     drives?: IClusterDriveHealth[];
     erasure?: IClusterErasureHealth;
     repairs?: IClusterRepairHealth;
+    transport?: IClusterTransportHealth;
+}
+/**
+ * The result of one cluster healing scan, as `ObjectStorage.runHealingScan()`
+ * returns it. Times are milliseconds since the Unix epoch.
+ */
+export interface IClusterHealingScanResult {
+    /** When the scan started; always after the request arrived. */
+    startedAt: number;
+    completedAt: number;
+    durationMs: number;
+    /** Shard placements checked at their drives (placements on offline nodes are not). */
+    shardsChecked: number;
+    /** Shards written: missing placements rebuilt and pending shards completed. */
+    shardsHealed: number;
+    /** Pending shards (writes that failed at publication) this scan left pending. */
+    shardsPending: number;
+    /** Failed checks, rebuilds, writes and manifest stores. */
+    failed: number;
+}
+export interface IRunHealingScanOptions {
+    /**
+     * How long to wait for the scan, in milliseconds. Defaults to the bridge's
+     * request timeout (300,000). The engine cannot cancel a scan: one that
+     * outlasts this keeps running, its result is discarded, and a later call
+     * joins the next scan that starts after it.
+     */
+    timeoutMs?: number;
 }
 /**
  * Main ObjectStorage class - production-ready S3-compatible storage server
@@ -737,11 +910,15 @@ export declare class ObjectStorage {
     private bridgeOwned;
     private stopRequested;
     private stopCompleted;
+    private readonly dashboardConfig;
+    private dashboard;
     constructor(configArg?: IObjectStorageConfig);
     start(): Promise<void>;
     private startInternal;
     /** Actual TCP port while running; the requested config port before/afterward. */
     get port(): number;
+    /** The dashboard's bound TCP port while it runs; `undefined` otherwise. */
+    get dashboardPort(): number | undefined;
     getStorageDescriptor(optionsArg?: Partial<plugins.tsclass.storage.IS3Descriptor>): Promise<plugins.tsclass.storage.IS3Descriptor>;
     private getEndpoint;
     private buildBucketTenantDescriptor;
@@ -757,6 +934,27 @@ export declare class ObjectStorage {
     getBucketTenantDescriptor(optionsArg: {
         bucketName: string;
     }): Promise<IBucketTenantDescriptor>;
+    /**
+     * Creates a credential confined to one key prefix of one bucket until its
+     * expiry. The first node takes `ttlSeconds`; further nodes of a fan-out take
+     * the first result's `accessKeyId`, `secretAccessKey` and `expiresAt`. The
+     * secret is returned only here and never kept by this instance.
+     */
+    createPrefixCredential(inputArg: IPrefixCredentialInput): Promise<IPrefixCredential>;
+    /**
+     * Revokes a prefix credential on this node. An unknown ID is recorded as
+     * revoked too, so a later create for it is refused; `revoked` is true only
+     * when a live credential was removed.
+     */
+    revokePrefixCredential(optionsArg: {
+        accessKeyId: string;
+    }): Promise<{
+        revoked: boolean;
+    }>;
+    /** Lists this node's live prefix credentials, without secrets. */
+    listPrefixCredentials(optionsArg?: {
+        bucketName?: string;
+    }): Promise<IPrefixCredentialMetadata[]>;
     getBucketRetentionCapability(): Promise<IBucketRetentionCapability>;
     getBucketRetentionReceipt(optionsArg: {
         bucketName: string;
@@ -789,6 +987,26 @@ export declare class ObjectStorage {
      */
     replaceCredentials(credentials: IStorageCredential[]): Promise<void>;
     getClusterHealth(): Promise<IClusterHealth>;
+    /**
+     * The dashboard's snapshot, built by the engine from memory only: it never
+     * probes a drive, syncs or walks storage. A cluster node also asks each
+     * online peer for its own snapshot, waiting up to a second per peer, in
+     * parallel; a peer that does not answer is reported unavailable. One
+     * snapshot runs at a time: a call while another runs rejects.
+     */
+    getClusterSnapshot(): Promise<IObjectStorageClusterSnapshot>;
+    /**
+     * Runs a healing scan on this cluster node and resolves with its result.
+     * The scan covers the manifests this node coordinated. The request joins
+     * the next scan that starts after it arrives, never one already running,
+     * and requests that arrive together share one scan. It rejects in
+     * standalone mode, when the scan fails (for example without a majority of
+     * the cluster, or when a bucket's manifests cannot be listed), when 16
+     * requests already wait for a scan to start, and when the engine shuts down
+     * before the scan completes. The engine answers other management calls
+     * while the scan runs.
+     */
+    runHealingScan(optionsArg?: IRunHealingScanOptions): Promise<IClusterHealingScanResult>;
     getHealth(): Promise<IObjectStorageHealth>;
     getMetrics(): Promise<IObjectStorageMetrics>;
     /**