@serve.zone/interfaces 17.3.0 → 17.5.0

package/ts/appstore/types.ts

@@ -4,12 +4,103 @@ import type {
   IServicePublicPortMapping,
   IServiceTargetPort,
 } from '../data/serviceports.js';
+import type {
+  IStorageCapacityRequest,
+  IStorageClassRequirement,
+  TFilesystemStorageAccessMode,
+  TObjectStorageAccessMode,
+  TObjectStorageDelivery,
+  TStorageReclaimPolicy,
+  TStorageResourceKind,
+  TStorageSnapshotMode,
+} from '../platform/storage.js';
 
 export type TAppStorePlatformRequirement = 'mongodb' | 's3' | 'clickhouse' | 'valkey' | 'mariadb';
+export interface IAppStorePlatformRequirements {
+  mongodb?: boolean;
+  /**
+   * @deprecated `s3: true` is normalized to one legacy object-storage binding.
+   * New templates use a named objectStorage request.
+   */
+  s3?: boolean;
+  clickhouse?: boolean;
+  valkey?: boolean;
+  mariadb?: boolean;
+}
 export type TAppStoreSourceType = 'inline' | 'repoManifest' | 'dockerImage';
 export type TAppStoreTrackingMode = 'tag' | 'digest';
 export type TAppStoreUpgradeStrategy = 'semver' | 'branch' | 'dockerDigest';
 
+export const appStoreStorageFeatureIds = {
+  bindingsV1: 'storage.bindings.v1',
+  filesystemV1: 'storage.filesystem.v1',
+  objectStorageV1: 'storage.object-storage.v1',
+  objectStorageSecretFileV1: 'storage.object-storage.secret-file.v1',
+} as const;
+
+export type TAppStoreStorageFeatureId =
+  typeof appStoreStorageFeatureIds[keyof typeof appStoreStorageFeatureIds];
+
+export type TAppStoreStoragePurpose =
+  | 'runtime'
+  | 'database'
+  | 'registry'
+  | 'backup';
+
+/**
+ * A template-local logical class. It states portable policy requirements and
+ * preferences; fulfillment adapters select their own compatible policy class.
+ */
+export interface IAppStoreStorageClass {
+  kind: TStorageResourceKind;
+  purpose: TAppStoreStoragePurpose;
+  required?: IStorageClassRequirement;
+  preferred?: IStorageClassRequirement;
+}
+
+export interface IAppStoreStorageRequestBase {
+  /** Stable identity used across upgrades, migrations, and restores. */
+  id: string;
+  kind: TStorageResourceKind;
+  /** Key in the containing version config's storageClasses record. */
+  storageClass: string;
+  capacity?: IStorageCapacityRequest;
+  reclaimPolicy: TStorageReclaimPolicy;
+}
+
+export interface IAppStoreFilesystemProtection {
+  backup?: 'required';
+  snapshots?: Exclude<TStorageSnapshotMode, 'none'>;
+  consistency?: 'crashConsistent' | 'applicationConsistent';
+}
+
+export interface IAppStoreFilesystemStorageRequest
+extends IAppStoreStorageRequestBase {
+  kind: 'filesystem';
+  mountPath: string;
+  accessMode: TFilesystemStorageAccessMode;
+  protection?: IAppStoreFilesystemProtection;
+}
+
+export interface IAppStoreObjectStorageProtection {
+  backup?: 'required';
+  versioning?: 'required';
+  /** Minimum provider-enforced retention duration. */
+  retentionDays?: number;
+}
+
+export interface IAppStoreObjectStorageRequest
+extends IAppStoreStorageRequestBase {
+  kind: 'objectStorage';
+  accessMode: TObjectStorageAccessMode;
+  delivery: TObjectStorageDelivery;
+  protection?: IAppStoreObjectStorageProtection;
+}
+
+export type TAppStoreStorageRequest =
+  | IAppStoreFilesystemStorageRequest
+  | IAppStoreObjectStorageRequest;
+
 export interface IAppStoreInlineSource {
   type: 'inline';
 }
@@ -140,9 +231,21 @@ export interface IAppStoreVersionConfig {
   /** Edge/coretraffic public TCP/UDP exposure, distinct from Docker publishedPorts. */
   publicPortMappings?: IServicePublicPortMapping[];
   envVars?: IAppStoreEnvVar[];
+  /**
+   * @deprecated Legacy volume syntax. New templates use storageClasses and
+   * storageRequests. Resolver normalization must reject legacy physical driver
+   * options that cannot be represented portably.
+   */
   volumes?: TAppStoreVolumeSpec[];
+  /**
+   * Template-local logical policy classes. Keys are stable within the
+   * template; they are not Onebox or Cloudly operator class names.
+   */
+  storageClasses?: Record<string, IAppStoreStorageClass>;
+  /** Stable named filesystem and managed object-storage requests. */
+  storageRequests?: TAppStoreStorageRequest[];
   publishedPorts?: IAppStorePublishedPort[];
-  platformRequirements?: Partial<Record<TAppStorePlatformRequirement, boolean>>;
+  platformRequirements?: IAppStorePlatformRequirements;
   minOneboxVersion?: string;
   minCloudlyVersion?: string;
   appStoreVersion?: string;

package/ts/data/deploymentoperation.ts

@@ -222,9 +222,11 @@ export const validateDeploymentProposedConfiguration = (
     errors.push('volumeMounts must be canonical supported declarations');
   }
   if (!Array.isArray(configurationArg.requiredCapabilities)
-    || configurationArg.requiredCapabilities.length > 2
+    || configurationArg.requiredCapabilities.length > 3
     || configurationArg.requiredCapabilities.some((capabilityArg) => (
-      capabilityArg !== 'database' && capabilityArg !== 'objectstorage'
+      capabilityArg !== 'database'
+      && capabilityArg !== 'objectstorage'
+      && capabilityArg !== 'pushnotification'
     ))
     || new Set(configurationArg.requiredCapabilities).size
       !== configurationArg.requiredCapabilities.length) {

package/ts/data/deploymentpreflight.ts

@@ -98,7 +98,7 @@ export interface IDeploymentPreflightRuntimeTask {
 }
 
 export interface IDeploymentPreflightPlatformBinding {
-  capability: 'database' | 'objectstorage';
+  capability: 'database' | 'objectstorage' | 'pushnotification';
   desiredState: 'enabled' | 'disabled';
   status: 'requested' | 'provisioning' | 'ready' | 'degraded' | 'failed' | 'disabled';
 }
@@ -139,7 +139,7 @@ export interface IDeploymentPreflightProposedConfiguration {
   secretFiles?: IServiceSecretFile[];
   containerPorts: number[];
   volumeMounts: IDeploymentPreflightProposedVolumeMount[];
-  requiredCapabilities: Array<'database' | 'objectstorage'>;
+  requiredCapabilities: Array<'database' | 'objectstorage' | 'pushnotification'>;
 }
 
 export interface IDeploymentReleaseEvidenceReference {

package/ts/data/gateway.ts

@@ -131,6 +131,13 @@ export interface IGatewayCapabilities {
   http3: {
     enabled: boolean;
   };
+  /** Absent means that this gateway does not advertise Web Push support. */
+  webPush?: {
+    bindings: boolean;
+    delivery: boolean;
+    cancellation: boolean;
+    vapidRotation: boolean;
+  };
 }
 
 /**
@@ -146,6 +153,8 @@ export interface IGatewayTokenCapabilities {
   manageMail?: boolean;
   readCertificates?: boolean;
   requestCertificates?: boolean;
+  readWebPush?: boolean;
+  manageWebPush?: boolean;
 }
 
 /**

package/ts/data/index.ts

@@ -33,3 +33,4 @@ export * from './taskexecution.js';
 export * from './traffic.js';
 export * from './user.js';
 export * from './version.js';
+export * from './webpush.js';

package/ts/data/service.ts

@@ -3,6 +3,7 @@ import type { IRegistryTarget } from './registry.js';
 import type { IAppStorePublishedPort } from '../appstore/index.js';
 import type { IHostedAppLifecycleState } from './hostedapp.js';
 import type { IServiceMailConfig } from './mail.js';
+import type { IServiceWebPushConfig } from './webpush.js';
 import type {
   IImageRolloutStatus,
   IImmutableImageDeploymentPlan,
@@ -326,6 +327,7 @@ export interface IService {
       custom?: { [domain: string]: string };
     };
     mail?: IServiceMailConfig;
+    webPush?: IServiceWebPushConfig;
     volumes?: IServiceVolume[];
     publishedPorts?: IAppStorePublishedPort[];
     /** Edge/coretraffic public TCP/UDP exposure, distinct from Docker Swarm publishedPorts. */

package/ts/data/webpush.ts

@@ -0,0 +1,133 @@
+import type { TGatewayClientType } from './gateway.js';
+
+export type TWebPushBindingStatus = 'active' | 'disabled' | 'pending' | 'failed';
+
+export type TWebPushCredentialStatus = 'active' | 'disabled' | 'rotated' | 'revoked';
+
+export type TWebPushVapidKeyStatus = 'active' | 'retiring' | 'retired';
+
+/**
+ * `pushServiceAccepted` means that the remote push service accepted the
+ * encrypted request. It does not prove browser receipt or display.
+ */
+export type TWebPushDeliveryState =
+  | 'accepted'
+  | 'queued'
+  | 'sending'
+  | 'deferred'
+  | 'pushServiceAccepted'
+  | 'invalidSubscription'
+  | 'failed'
+  | 'expired'
+  | 'cancelled';
+
+export type TWebPushUrgency = 'very-low' | 'low' | 'normal' | 'high';
+
+/**
+ * `appInstanceId` identifies the environment-specific deployed service
+ * instance, not an App Store template or a browser-provided owner.
+ */
+export interface IWebPushResourceOwner {
+  gatewayClientType: TGatewayClientType;
+  gatewayClientId: string;
+  appInstanceId: string;
+}
+
+/** JSON form returned by the browser Push API. */
+export interface IWebPushSubscription {
+  endpoint: string;
+  expirationTime: number | null;
+  keys: {
+    p256dh: string;
+    auth: string;
+  };
+}
+
+export interface IWebPushCredentialPublic {
+  id: string;
+  status: TWebPushCredentialStatus;
+  createdAt: number;
+  updatedAt: number;
+  lastRotatedAt?: number;
+}
+
+export interface IWebPushCredentialOneTimeSecret {
+  credential: IWebPushCredentialPublic;
+  secret: string;
+  secretShownOnce: true;
+}
+
+export interface IWebPushVapidKeyPublic {
+  id: string;
+  publicKey: string;
+  status: TWebPushVapidKeyStatus;
+  createdAt: number;
+  activatedAt?: number;
+  retireAfter?: number;
+  retiredAt?: number;
+}
+
+export interface IWebPushBinding {
+  id: string;
+  owner: IWebPushResourceOwner;
+  enabled: boolean;
+  status: TWebPushBindingStatus;
+  credential?: IWebPushCredentialPublic;
+  vapidKeys: IWebPushVapidKeyPublic[];
+  createdAt: number;
+  updatedAt: number;
+  createdBy?: string;
+}
+
+/**
+ * Privacy-minimal notification signal. Applications fetch display content
+ * from their authenticated API after receiving this event.
+ */
+export interface IWebPushNotificationPayload {
+  schemaVersion: 1;
+  event: 'notificationAvailable';
+  eventId: string;
+  /** Same-origin application route beginning with a single slash. */
+  route: string;
+}
+
+/** Public delivery metadata. Subscription and encrypted payload data are absent. */
+export interface IWebPushDeliveryStatus {
+  spoolItemId: string;
+  state: TWebPushDeliveryState;
+  attempts: number;
+  acceptedAt: number;
+  updatedAt: number;
+  nextAttemptAt?: number;
+  terminalAt?: number;
+  pushServiceStatusCode?: number;
+  errorCode?: string;
+}
+
+export interface IWebPushServiceStatus {
+  ready: boolean;
+  bindingId: string;
+  bindingStatus: TWebPushBindingStatus;
+  activeVapidKey?: IWebPushVapidKeyPublic;
+  retiringVapidKeys: IWebPushVapidKeyPublic[];
+  maxPayloadBytes: number;
+  maxTtlSeconds: number;
+  contentEncoding: 'aes128gcm';
+  message?: string;
+}
+
+export type TWebPushCancellationTarget =
+  | {
+      type: 'spoolItem';
+      spoolItemId: string;
+      subscriptionId?: never;
+    }
+  | {
+      type: 'subscription';
+      subscriptionId: string;
+      spoolItemId?: never;
+    };
+
+export interface IServiceWebPushConfig {
+  enabled?: boolean;
+}

package/ts/platform/index.ts

@@ -8,6 +8,7 @@ import * as objectstorage from './objectstorage.js';
 import * as pushnotification from './pushnotification.js';
 import * as sip from './sip.js';
 import * as sms from './sms.js';
+import * as storage from './storage.js';
 import * as types from './types.js';
 
 export {
@@ -21,7 +22,9 @@ export {
   pushnotification,
   sip,
   sms,
+  storage,
   types,
 };
 
+export * from './storage.js';
 export * from './types.js';

package/ts/platform/pushnotification.ts

@@ -1,5 +1,6 @@
 import * as plugins from '../plugins.js';
 
+/** @deprecated Use the credential-scoped requests.webpush contracts. */
 export interface IReq_SendPushNotification extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest,
   IReq_SendPushNotification

package/ts/platform/storage.ts

@@ -0,0 +1,237 @@
+/**
+ * Backend-neutral storage vocabulary shared by App Store manifests, control
+ * planes, and fulfillment adapters. Physical providers and runtime attachment
+ * details intentionally do not belong in these contracts.
+ */
+export type TStorageResourceKind = 'filesystem' | 'objectStorage';
+/**
+ * Compatibility bridge for the existing generic platform capability. New
+ * filesystem requests intentionally have no generic IPlatformBinding mapping.
+ */
+export const storageKindPlatformCapabilityIds = {
+  objectStorage: 'objectstorage',
+} as const;
+export type TFilesystemStorageAccessMode =
+  | 'ReadWriteOnce'
+  | 'ReadOnlyMany'
+  | 'ReadWriteMany';
+export type TObjectStorageAccessMode = 'readOnly' | 'readWrite';
+export type TStoragePerformanceTier = 'standard' | 'highIops' | 'capacity';
+export type TStorageDurability = 'ephemeral' | 'persistent';
+export type TStorageTopology = 'singleNode' | 'multiNode';
+export type TStorageSnapshotMode = 'none' | 'portable' | 'native';
+export type TStorageReclaimPolicy = 'retain' | 'delete';
+
+/**
+ * A positive base-2 quantity written as an integer followed by KiB, MiB, GiB,
+ * or TiB, for example `20GiB`. Parsers must reject every other representation.
+ */
+export type TStorageCapacityQuantity = string;
+
+export interface IStorageCapacityRequest {
+  request: TStorageCapacityQuantity;
+  /**
+   * A hard upper bound. A request with a limit can only be fulfilled by a
+   * class whose granted capabilities include hardQuota.
+   */
+  limit?: TStorageCapacityQuantity;
+}
+
+/**
+ * App-facing requirements describe policy, never a concrete provider class.
+ * Values in a `required` block are hard constraints; values in `preferred`
+ * influence selection but may not weaken required constraints.
+ */
+export interface IStorageClassRequirement {
+  performanceTier?: TStoragePerformanceTier;
+  durability?: TStorageDurability;
+  topology?: TStorageTopology;
+  hardQuota?: true;
+  snapshots?: Exclude<TStorageSnapshotMode, 'none'>;
+  backup?: true;
+  encryptedInTransit?: true;
+}
+
+export interface IStorageGrantedCapabilities {
+  performanceTier: TStoragePerformanceTier;
+  durability: TStorageDurability;
+  topology: TStorageTopology;
+  hardQuota: boolean;
+  snapshots: TStorageSnapshotMode;
+  backup: boolean;
+  encryptedInTransit: boolean;
+}
+
+export interface IStorageClassCapabilitiesBase {
+  /** Opaque operator-defined policy class ID, not a physical backend name. */
+  classId: string;
+  /** Changes whenever matching behavior or guarantees change. */
+  revision: string;
+  kind: TStorageResourceKind;
+  performanceTiers: TStoragePerformanceTier[];
+  durabilities: TStorageDurability[];
+  topologies: TStorageTopology[];
+  hardQuota: boolean;
+  snapshotModes: TStorageSnapshotMode[];
+  backup: boolean;
+  encryptedInTransit: boolean;
+}
+
+export interface IFilesystemStorageClassCapabilities
+extends IStorageClassCapabilitiesBase {
+  kind: 'filesystem';
+  accessModes: TFilesystemStorageAccessMode[];
+}
+
+export interface IObjectStorageClassCapabilities
+extends IStorageClassCapabilitiesBase {
+  kind: 'objectStorage';
+  accessModes: TObjectStorageAccessMode[];
+  versioning: boolean;
+  retention: boolean;
+}
+
+export type TStorageClassCapabilities =
+  | IFilesystemStorageClassCapabilities
+  | IObjectStorageClassCapabilities;
+
+/**
+ * Fulfillment adapters advertise only portable guarantees. Provider names,
+ * addresses, mount options, principals, and credential values are private.
+ */
+export interface IStorageCapabilityAdvertisement {
+  schemaVersion: 1;
+  featureIds: string[];
+  classes: TStorageClassCapabilities[];
+}
+
+export interface IObjectStorageEnvironmentDelivery {
+  type: 'environment';
+  /**
+   * Explicit target keys prevent two named bindings from silently overwriting
+   * each other. Every required field must have a distinct environment key.
+   */
+  keys: {
+    endpoint: string;
+    bucket: string;
+    region: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken?: string;
+  };
+}
+
+export interface IObjectStorageSecretFileDelivery {
+  type: 'secretFile';
+  /** Canonical absolute path below /run/secrets/. */
+  targetPath: string;
+  /**
+   * JSON object with endpoint, bucket, region, accessKeyId,
+   * secretAccessKey, and optional sessionToken fields.
+   */
+  format: 'servezone-object-storage-v1';
+}
+
+export type TObjectStorageDelivery =
+  | IObjectStorageEnvironmentDelivery
+  | IObjectStorageSecretFileDelivery;
+
+export type TResolvedStorageBindingStatus =
+  | 'requested'
+  | 'provisioning'
+  | 'ready'
+  | 'degraded'
+  | 'failed'
+  | 'releasing'
+  | 'retained'
+  | 'released';
+
+export type TStorageBindingFailureCode =
+  | 'unsupportedCapability'
+  | 'policyUnavailable'
+  | 'provisionFailed'
+  | 'attachmentFailed'
+  | 'quotaExceeded'
+  | 'credentialsUnavailable'
+  | 'backendUnavailable'
+  | 'migrationRequired';
+
+export interface IStorageBindingFailure {
+  code: TStorageBindingFailureCode;
+  message: string;
+  retryable: boolean;
+  observedAt: number;
+}
+
+export interface IResolvedStoragePolicyRef {
+  /** Opaque operator-defined policy class ID selected for this request. */
+  classId: string;
+  revision: string;
+}
+
+export interface IResolvedStorageCapacity {
+  requested?: TStorageCapacityQuantity;
+  granted?: TStorageCapacityQuantity;
+  limit?: TStorageCapacityQuantity;
+}
+
+export interface IResolvedStorageBindingBase {
+  schemaVersion: 1;
+  /** Stable binding/allocation identity. */
+  id: string;
+  serviceId: string;
+  /** Stable App Store storageRequests[].id. */
+  requestId: string;
+  /**
+   * Canonical digest of the normalized request. Adapters use it to distinguish
+   * an idempotent reconciliation from a migration.
+   */
+  requestDigest: string;
+  kind: TStorageResourceKind;
+  generation: number;
+  observedGeneration: number;
+  status: TResolvedStorageBindingStatus;
+  policy: IResolvedStoragePolicyRef;
+  capabilities: IStorageGrantedCapabilities;
+  /** Opaque resource identity; never a host path, export, or provider URL. */
+  resourceRef: string;
+  capacity?: IResolvedStorageCapacity;
+  failure?: IStorageBindingFailure;
+  createdAt?: number;
+  updatedAt?: number;
+}
+
+export interface IResolvedFilesystemStorageBinding
+extends IResolvedStorageBindingBase {
+  kind: 'filesystem';
+  mountPath: string;
+  accessMode: TFilesystemStorageAccessMode;
+}
+
+export interface IStorageObjectCredentialsRef {
+  secretBundleId: string;
+  accessKeyIdKey: string;
+  secretAccessKeyKey: string;
+  sessionTokenKey?: string;
+}
+
+export interface IResolvedObjectStorageConnection {
+  endpoint: string;
+  bucket: string;
+  region: string;
+}
+
+export interface IResolvedObjectStorageBinding
+extends IResolvedStorageBindingBase {
+  kind: 'objectStorage';
+  accessMode: TObjectStorageAccessMode;
+  connection: IResolvedObjectStorageConnection;
+  credentials: IStorageObjectCredentialsRef;
+  delivery: TObjectStorageDelivery;
+  versioning: boolean;
+  retentionDays?: number;
+}
+
+export type TResolvedStorageBinding =
+  | IResolvedFilesystemStorageBinding
+  | IResolvedObjectStorageBinding;

package/ts/platformservice/pushnotification.ts

@@ -1,5 +1,6 @@
 import * as plugins from '../plugins.js';
 
+/** @deprecated Use the credential-scoped requests.webpush contracts. */
 export interface IRequest_SendPushNotification extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest,
   IRequest_SendPushNotification

package/ts/requests/index.ts

@@ -33,6 +33,7 @@ import * as settingsRequests from './settings.js';
 import * as statusRequests from './status.js';
 import * as taskRequests from './task.js';
 import * as versionRequests from './version.js';
+import * as webPushRequests from './webpush.js';
 
 export {
   adminRequests as admin,
@@ -68,8 +69,10 @@ export {
   statusRequests as status,
   taskRequests as task,
   versionRequests as version,
+  webPushRequests as webpush,
 };
 
 export * from './inform.js';
 export * from './hostedapp.js';
 export * from './mail.js';
+export * from './webpush.js';