@lossless.org/objectstorage 10.7.1 → 11.1.0

package/ts/dashboard.interfaces.ts

@@ -0,0 +1,148 @@
+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/ts/dashboard.plugins.ts

@@ -0,0 +1,13 @@
+// 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 };