@lossless.org/objectstorage 11.0.0 → 11.2.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
  */
@@ -125,11 +127,33 @@ export interface IDriveConfig {
      */
     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[];
@@ -147,11 +171,17 @@ export interface IClusterConfig {
      * 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
  */
@@ -171,16 +201,32 @@ 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.
  * Values are initialized from native storage on startup and updated on objectstorage mutations.
  */
+/** A versioned bucket's S3 versioning status; a bucket that was never versioned has none. */
+export type TBucketVersioningStatus = 'Enabled' | 'Suspended';
 export interface IBucketSummary {
     name: string;
+    /** Current objects; noncurrent versions and delete markers are counted below. */
     objectCount: number;
     totalSizeBytes: number;
     creationDate?: number;
+    /** Present only for a versioned bucket (standalone), and so are the counters below. */
+    versioning?: TBucketVersioningStatus;
+    /** Noncurrent data versions. */
+    noncurrentVersionCount?: number;
+    /** Payload bytes of the noncurrent data versions. */
+    noncurrentBytes?: number;
+    /** Delete markers, current and noncurrent. */
+    deleteMarkerCount?: number;
 }
 /**
  * Filesystem-level capacity snapshot for the storage directory or configured drive path.
@@ -278,6 +324,15 @@ export interface IStorageStats {
     buckets: IBucketSummary[];
     storageDirectory: string;
     storageLocations?: IStorageLocationSummary[];
+    /** Totals over the versioned buckets; absent without one. */
+    totalNoncurrentVersionCount?: number;
+    totalNoncurrentBytes?: number;
+    totalDeleteMarkerCount?: number;
+    /**
+     * How far version stamps run ahead of the wall clock, after the wall clock
+     * went backwards (or a forward jump was corrected); absent when they do not.
+     */
+    stampClockAheadOfWallMs?: number;
 }
 export interface IStorageStopResult {
     complete: true;
@@ -691,6 +746,8 @@ export interface IObjectStorageHealth {
     resourcePublicationHoldSupported: boolean;
     resourcePublicationHoldRequiresExternalDrain: false;
     resourceFencingReason?: string;
+    /** See `IStorageStats.stampClockAheadOfWallMs`. */
+    stampClockAheadOfWallMs?: number;
 }
 export declare const objectStorageResourceFenceErrorCodes: readonly ['EFENCE_REQUIRED', 'EFENCE_STALE', 'EFENCE_SCOPE_MISMATCH', 'EFENCE_UNSUPPORTED', 'EFENCE_MUTATION_MISMATCH', 'EFENCE_STATE_CORRUPT', 'EFENCE_RECEIPT_LIMIT', 'EFENCE_BUSY', 'EFENCE_OWNERSHIP_MISMATCH', 'EFENCE_PUBLICATION_HELD', 'EFENCE_PUBLICATION_MISMATCH', 'EFENCE_PUBLICATION_CAPABILITY'];
 export type TObjectStorageResourceFenceErrorCode = (typeof objectStorageResourceFenceErrorCodes)[number];
@@ -725,6 +782,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.
  */
@@ -739,6 +823,7 @@ export interface IClusterDriveHealth {
     lastError?: string;
     lastCheck?: number;
     erasureSetId?: number;
+    media: IClusterDriveMedia;
 }
 export interface IClusterErasureHealth {
     dataShards: number;
@@ -762,6 +847,23 @@ export interface IClusterRepairHealth {
     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 }`.
@@ -777,6 +879,7 @@ export interface IClusterHealth {
     drives?: IClusterDriveHealth[];
     erasure?: IClusterErasureHealth;
     repairs?: IClusterRepairHealth;
+    transport?: IClusterTransportHealth;
 }
 /**
  * The result of one cluster healing scan, as `ObjectStorage.runHealingScan()`
@@ -829,11 +932,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;
@@ -902,6 +1009,14 @@ 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