Add session lifecycle truapi interface

Author: replghost

docs/rfcs/0016-product-session-restore.md

@@ -194,7 +194,7 @@ enum SessionLifecycleEvent {
 struct SessionLifecycleRequest {
   event_id: SessionLifecycleEventId,
   reason: SessionLifecycleReason,
-  deadline_ms: Option<u32>,
+  deadline_ms: Option<TimestampMs>,
 }
 
 enum SessionLifecycleReason {

js/packages/truapi/src/generated/client.ts

@@ -1120,6 +1120,80 @@ export class ResourceAllocationClient {
   }
 }
 
+/**
+ * Product session lifecycle operations.
+ *
+ * Default methods return [`CallError::HostFailure`] with an `unavailable`
+ * reason. Hosts override when they support product session restore.
+ */
+export class SessionClient {
+  constructor(private readonly transport: TrUApiTransport) {}
+
+  /**
+   * Subscribe to host lifecycle signals so a product can checkpoint semantic
+   * session state through scoped local storage before suspend, eviction, or
+   * close.
+   *
+   * ```truapi-client-example
+   * import {
+   *  type Client,
+   *  type HostSessionLifecycleSubscribeError,
+   *  type HostSessionLifecycleSubscribeItem,
+   *  type Subscription,
+   *  type SubscriptionError,
+   * } from "@parity/truapi";
+   *
+   * export function watchSessionLifecycle(truapi: Client): Subscription {
+   *  return truapi.session
+   *    .sessionLifecycleSubscribe({
+   *      request: { replayCurrentState: true },
+   *    })
+   *    .subscribe({
+   *      next: (event: HostSessionLifecycleSubscribeItem) =>
+   *        console.log(event),
+   *      error: (error: SubscriptionError<HostSessionLifecycleSubscribeError>) =>
+   *        console.error(error),
+   *      complete: () => console.log("completed"),
+   *    });
+   * }
+   * ```
+   */
+  lifecycleSubscribe({
+    request,
+  }: {
+    request: T.HostSessionLifecycleSubscribeRequest;
+  }): ObservableLike<
+    T.HostSessionLifecycleSubscribeItem,
+    T.HostSessionLifecycleSubscribeError
+  > {
+    return createObservable<
+      T.HostSessionLifecycleSubscribeItem,
+      T.HostSessionLifecycleSubscribeError
+    >({
+      transport: this.transport,
+      ids: W.SESSION_LIFECYCLE_SUBSCRIBE,
+      payload: T.VersionedHostSessionLifecycleSubscribeRequest.enc({
+        tag: "V1",
+        value: request,
+      }),
+      decodeItem: (payload) =>
+        (
+          T.VersionedHostSessionLifecycleSubscribeItem.dec(payload) as {
+            tag: "V1";
+            value: T.HostSessionLifecycleSubscribeItem;
+          } & T.VersionedHostSessionLifecycleSubscribeItem
+        ).value,
+      decodeInterrupt: (payload) =>
+        (
+          T.VersionedHostSessionLifecycleSubscribeError.dec(payload) as {
+            tag: "V1";
+            value: T.HostSessionLifecycleSubscribeError;
+          } & T.VersionedHostSessionLifecycleSubscribeError
+        ).value,
+    });
+  }
+}
+
 /** Signing operations. */
 export class SigningClient {
   constructor(private readonly transport: TrUApiTransport) {}
@@ -1526,6 +1600,7 @@ export interface TrUApiClient {
   readonly permissions: PermissionsClient;
   readonly preimage: PreimageClient;
   readonly resourceAllocation: ResourceAllocationClient;
+  readonly session: SessionClient;
   readonly signing: SigningClient;
   readonly statementStore: StatementStoreClient;
   readonly system: SystemClient;
@@ -1567,6 +1642,7 @@ export function createClient(
     permissions: new PermissionsClient(versionedTransport),
     preimage: new PreimageClient(versionedTransport),
     resourceAllocation: new ResourceAllocationClient(versionedTransport),
+    session: new SessionClient(versionedTransport),
     signing: new SigningClient(versionedTransport),
     statementStore: new StatementStoreClient(versionedTransport),
     system: new SystemClient(versionedTransport),

js/packages/truapi/src/generated/types.ts

@@ -1580,6 +1580,48 @@ export const VersionedHostRequestResourceAllocationResponse: S.Codec<VersionedHo
       }),
   );
 
+/** Versioned envelope for [`HostSessionLifecycleSubscribeError`]. */
+export type VersionedHostSessionLifecycleSubscribeError = {
+  tag: "V1";
+  value: HostSessionLifecycleSubscribeError;
+};
+
+export const VersionedHostSessionLifecycleSubscribeError: S.Codec<VersionedHostSessionLifecycleSubscribeError> =
+  S.lazy(
+    (): S.Codec<VersionedHostSessionLifecycleSubscribeError> =>
+      S.indexedTaggedUnion({
+        V1: [0, HostSessionLifecycleSubscribeError] as const,
+      }),
+  );
+
+/** Versioned envelope for [`HostSessionLifecycleSubscribeItem`]. */
+export type VersionedHostSessionLifecycleSubscribeItem = {
+  tag: "V1";
+  value: HostSessionLifecycleSubscribeItem;
+};
+
+export const VersionedHostSessionLifecycleSubscribeItem: S.Codec<VersionedHostSessionLifecycleSubscribeItem> =
+  S.lazy(
+    (): S.Codec<VersionedHostSessionLifecycleSubscribeItem> =>
+      S.indexedTaggedUnion({
+        V1: [0, HostSessionLifecycleSubscribeItem] as const,
+      }),
+  );
+
+/** Versioned envelope for [`HostSessionLifecycleSubscribeRequest`]. */
+export type VersionedHostSessionLifecycleSubscribeRequest = {
+  tag: "V1";
+  value: HostSessionLifecycleSubscribeRequest;
+};
+
+export const VersionedHostSessionLifecycleSubscribeRequest: S.Codec<VersionedHostSessionLifecycleSubscribeRequest> =
+  S.lazy(
+    (): S.Codec<VersionedHostSessionLifecycleSubscribeRequest> =>
+      S.indexedTaggedUnion({
+        V1: [0, HostSessionLifecycleSubscribeRequest] as const,
+      }),
+  );
+
 /** Versioned envelope for [`HostSignPayloadError`]. */
 export type VersionedHostSignPayloadError = {
   tag: "V1";
@@ -2743,6 +2785,53 @@ export const RuntimeType: S.Codec<RuntimeType> = S.lazy(
     }),
 );
 
+/** Host-assigned stable identifier for one lifecycle event. */
+export type SessionLifecycleEventId = string;
+
+export const SessionLifecycleEventId: S.Codec<SessionLifecycleEventId> = S.lazy(
+  (): S.Codec<SessionLifecycleEventId> => S.str,
+);
+
+/** Reason for a lifecycle checkpoint request. */
+export type SessionLifecycleReason =
+  | "AppSwitcher"
+  | "HostBackgrounded"
+  | "HostTerminating"
+  | "MemoryPressure"
+  | "UserClosedProduct"
+  | "HostPolicy";
+
+export const SessionLifecycleReason: S.Codec<SessionLifecycleReason> = S.lazy(
+  (): S.Codec<SessionLifecycleReason> =>
+    S.Status(
+      "AppSwitcher",
+      "HostBackgrounded",
+      "HostTerminating",
+      "MemoryPressure",
+      "UserClosedProduct",
+      "HostPolicy",
+    ),
+);
+
+/** Details for a single lifecycle checkpoint request. */
+export interface SessionLifecycleRequest {
+  /** Host-assigned event id for de-duplicating repeated notifications. */
+  eventId: SessionLifecycleEventId;
+  /** Reason the host is asking the product to checkpoint state. */
+  reason: SessionLifecycleReason;
+  /** Best-effort deadline for checkpoint completion. */
+  deadlineMs?: TimestampMs;
+}
+
+export const SessionLifecycleRequest: S.Codec<SessionLifecycleRequest> = S.lazy(
+  (): S.Codec<SessionLifecycleRequest> =>
+    S.Struct({
+      eventId: SessionLifecycleEventId,
+      reason: SessionLifecycleReason,
+      deadlineMs: S.Option(TimestampMs),
+    }) as S.Codec<SessionLifecycleRequest>,
+);
+
 /** Shape for borders and backgrounds. */
 export type Shape =
   /** Border radius value. */
@@ -2946,6 +3035,13 @@ export const Theme: S.Codec<Theme> = S.lazy(
   (): S.Codec<Theme> => S.Status("Light", "Dark"),
 );
 
+/** Milliseconds since the Unix epoch. */
+export type TimestampMs = bigint;
+
+export const TimestampMs: S.Codec<TimestampMs> = S.lazy(
+  (): S.Codec<TimestampMs> => S.u64,
+);
+
 /** 32-byte statement topic. */
 export type Topic = HexString;
 
@@ -3993,6 +4089,52 @@ export const HostRequestResourceAllocationResponse: S.Codec<HostRequestResourceA
       }) as S.Codec<HostRequestResourceAllocationResponse>,
   );
 
+/** Error from session lifecycle subscription setup. */
+export type HostSessionLifecycleSubscribeError =
+  /** The host does not support product session lifecycle events. */
+  | { tag: "Unsupported"; value?: undefined }
+  /** Catch-all. */
+  | { tag: "Unknown"; value: GenericErr };
+
+export const HostSessionLifecycleSubscribeError: S.Codec<HostSessionLifecycleSubscribeError> =
+  S.lazy(
+    (): S.Codec<HostSessionLifecycleSubscribeError> =>
+      S.TaggedUnion({ Unsupported: S._void, Unknown: GenericErr }),
+  );
+
+/** Lifecycle event emitted by the host before a product transition. */
+export type HostSessionLifecycleSubscribeItem =
+  /** The product should checkpoint state before it is suspended. */
+  | { tag: "WillSuspend"; value: SessionLifecycleRequest }
+  /** The product should checkpoint state before its WebView may be evicted. */
+  | { tag: "WillEvict"; value: SessionLifecycleRequest }
+  /** The product should checkpoint state before it is closed. */
+  | { tag: "WillClose"; value: SessionLifecycleRequest };
+
+export const HostSessionLifecycleSubscribeItem: S.Codec<HostSessionLifecycleSubscribeItem> =
+  S.lazy(
+    (): S.Codec<HostSessionLifecycleSubscribeItem> =>
+      S.TaggedUnion({
+        WillSuspend: SessionLifecycleRequest,
+        WillEvict: SessionLifecycleRequest,
+        WillClose: SessionLifecycleRequest,
+      }),
+  );
+
+/** Request to subscribe to host session lifecycle events. */
+export interface HostSessionLifecycleSubscribeRequest {
+  /** Ask the host to replay the current lifecycle state when one is active. */
+  replayCurrentState: boolean;
+}
+
+export const HostSessionLifecycleSubscribeRequest: S.Codec<HostSessionLifecycleSubscribeRequest> =
+  S.lazy(
+    (): S.Codec<HostSessionLifecycleSubscribeRequest> =>
+      S.Struct({
+        replayCurrentState: S.bool,
+      }) as S.Codec<HostSessionLifecycleSubscribeRequest>,
+  );
+
 export type HostSignPayloadError =
   | { tag: "FailedToDecode"; value?: undefined }
   | { tag: "Rejected"; value?: undefined }

js/packages/truapi/src/generated/wire-table.ts

@@ -306,3 +306,10 @@ export const STATEMENT_STORE_CREATE_PROOF_AUTHORIZED = {
   request: 132,
   response: 133,
 } as const satisfies RequestFrameIds;
+
+export const SESSION_LIFECYCLE_SUBSCRIBE = {
+  start: 162,
+  stop: 163,
+  interrupt: 164,
+  receive: 165,
+} as const satisfies SubscriptionFrameIds;

js/packages/truapi/src/playground/codegen/services.ts

@@ -365,6 +365,18 @@ export const services: ServiceInfo[] = [
       },
     ],
   },
+  {
+    name: "Session",
+    methods: [
+      {
+        name: "lifecycle_subscribe",
+        type: "subscription",
+        description:
+          'Subscribe to host lifecycle signals so a product can checkpoint semantic\nsession state through scoped local storage before suspend, eviction, or\nclose.\n\n```truapi-client-example\nimport {\n  type Client,\n  type HostSessionLifecycleSubscribeError,\n  type HostSessionLifecycleSubscribeItem,\n  type Subscription,\n  type SubscriptionError,\n} from "@parity/truapi";\n\nexport function watchSessionLifecycle(truapi: Client): Subscription {\n  return truapi.session\n    .sessionLifecycleSubscribe({\n      request: { replayCurrentState: true },\n    })\n    .subscribe({\n      next: (event: HostSessionLifecycleSubscribeItem) =>\n        console.log(event),\n      error: (error: SubscriptionError<HostSessionLifecycleSubscribeError>) =>\n        console.error(error),\n      complete: () => console.log("completed"),\n    });\n}\n```',
+        requestDescription: "HostSessionLifecycleSubscribeRequest",
+      },
+    ],
+  },
   {
     name: "Signing",
     methods: [

rust/crates/truapi/src/api/mod.rs

@@ -10,6 +10,7 @@ pub mod payment;
 pub mod permissions;
 pub mod preimage;
 pub mod resource_allocation;
+pub mod session;
 pub mod signing;
 pub mod statement_store;
 pub mod system;
@@ -25,6 +26,7 @@ pub use payment::Payment;
 pub use permissions::Permissions;
 pub use preimage::Preimage;
 pub use resource_allocation::ResourceAllocation;
+pub use session::Session;
 pub use signing::Signing;
 pub use statement_store::StatementStore;
 pub use system::System;
@@ -42,6 +44,7 @@ pub trait TrUApi:
     + Permissions
     + Preimage
     + ResourceAllocation
+    + Session
     + Signing
     + StatementStore
     + System
@@ -62,6 +65,7 @@ impl<T> TrUApi for T where
         + Permissions
         + Preimage
         + ResourceAllocation
+        + Session
         + Signing
         + StatementStore
         + System

rust/crates/truapi/src/api/session.rs

@@ -0,0 +1,53 @@
+//! Unified [`Session`] trait.
+
+use crate::versioned::session::{
+    HostSessionLifecycleSubscribeError, HostSessionLifecycleSubscribeItem,
+    HostSessionLifecycleSubscribeRequest,
+};
+use crate::wire;
+use crate::{CallContext, CallError, Subscription};
+
+/// Product session lifecycle operations.
+///
+/// Default methods return [`CallError::HostFailure`] with an `unavailable`
+/// reason. Hosts override when they support product session restore.
+pub trait Session: Send + Sync {
+    /// Subscribe to host lifecycle signals so a product can checkpoint semantic
+    /// session state through scoped local storage before suspend, eviction, or
+    /// close.
+    ///
+    /// ```truapi-client-example
+    /// import {
+    ///   type Client,
+    ///   type HostSessionLifecycleSubscribeError,
+    ///   type HostSessionLifecycleSubscribeItem,
+    ///   type Subscription,
+    ///   type SubscriptionError,
+    /// } from "@parity/truapi";
+    ///
+    /// export function watchSessionLifecycle(truapi: Client): Subscription {
+    ///   return truapi.session
+    ///     .sessionLifecycleSubscribe({
+    ///       request: { replayCurrentState: true },
+    ///     })
+    ///     .subscribe({
+    ///       next: (event: HostSessionLifecycleSubscribeItem) =>
+    ///         console.log(event),
+    ///       error: (error: SubscriptionError<HostSessionLifecycleSubscribeError>) =>
+    ///         console.error(error),
+    ///       complete: () => console.log("completed"),
+    ///     });
+    /// }
+    /// ```
+    #[wire(start_id = 162)]
+    async fn lifecycle_subscribe(
+        &self,
+        _cx: &CallContext,
+        _request: HostSessionLifecycleSubscribeRequest,
+    ) -> Result<
+        Subscription<HostSessionLifecycleSubscribeItem>,
+        CallError<HostSessionLifecycleSubscribeError>,
+    > {
+        Err(CallError::unavailable())
+    }
+}