@kestack/web-platform 0.0.0-stage → 0.0.1

package/src/app/host/host.ts

@@ -0,0 +1,166 @@
+import { Effect, Layer, Schema, Scope } from 'effect';
+import { type SignIn, signIn } from '@kestack/auth-toolkit/client';
+import {
+  type Broadcaster,
+  defaultBroadcaster,
+} from '@kestack/std-toolkit/core';
+import type { StdTableService, TableDefinition } from '@kestack/std-toolkit/db';
+import { Memory } from '@kestack/std-toolkit/db/memory';
+import { Sync, type SyncStore } from '@kestack/std-toolkit/sync';
+
+/** Where an app's Backend runs, and its Users sign in: in the cloud, or on
+ * this device, in the app itself. */
+export const Backend = Schema.Literals(['cloud', 'device']);
+export type Backend = typeof Backend.Type;
+
+// What the Backends were called before, as a device may still keep them.
+const FORMER: Readonly<Record<string, Backend>> = {
+  remote: 'cloud',
+  local: 'device',
+};
+
+/** The Backend `name` names, by its name or its former one (`remote`,
+ * `local`); null for anything else. */
+export const backendNamed = (
+  name: string | null | undefined,
+): Backend | null =>
+  name === 'cloud' || name === 'device'
+    ? name
+    : name == null
+      ? null
+      : (FORMER[name] ?? null);
+
+/** A table as a Host needs it to keep it. */
+export type TableSource<Name extends string> = Pick<
+  TableDefinition<Name>,
+  'logicalName' | 'primary' | 'localSecondaryIndexes' | 'globalSecondaryIndexes'
+>;
+
+/** What one tab tells the device's other tabs: look again. `quiet` are
+ * accounts it signed out itself, so they are not reported lost there. */
+export type TabMessage = { readonly quiet: ReadonlyArray<string> };
+
+/** Where a Host keeps things: a table adapter and a Sync adapter for the
+ * same place, such as IndexedDB in a browser or SQLite on a phone. */
+export interface Storage {
+  /** One table, kept in one of this device's databases, by name. */
+  readonly table: <Name extends string>(
+    table: TableSource<Name>,
+    database: string,
+  ) => Layer.Layer<StdTableService<Name>>;
+  /** What hears every write to one of this device's databases, by name:
+   * everyone writing to it here, such as every tab on one IndexedDB
+   * database, so a handler's change reaches every subscription. */
+  readonly broadcaster: (database: string) => Layer.Layer<Broadcaster>;
+  /** The Sync adapter here, where what a Std Sync keeps outlives the app so
+   * it opens offline, and every Std Sync kept on this device, by name. */
+  readonly sync: SyncStore & {
+    readonly list: () => Promise<ReadonlyArray<{ readonly name: string }>>;
+    readonly remove: (name: string) => Promise<void>;
+  };
+}
+
+/**
+ * One Broadcaster per database for as long as the app runs, made by `make`
+ * the first time a database is asked for and then given as it is, so every
+ * runtime that writes to the database shares it.
+ */
+export const keptBroadcasters = (
+  make: (database: string) => Layer.Layer<Broadcaster>,
+): Storage['broadcaster'] => {
+  const kept = new Map<string, Layer.Layer<Broadcaster>>();
+  return (database) => {
+    let layer = kept.get(database);
+    if (layer === undefined) {
+      layer = Layer.succeedContext(
+        Effect.runSync(
+          Layer.buildWithScope(make(database), Scope.makeUnsafe()),
+        ),
+      );
+      kept.set(database, layer);
+    }
+    return layer;
+  };
+};
+
+/**
+ * Everything an app needs of where it runs: its Storage, its cloud address
+ * and Sign-in, its lifecycle, and its other tabs if it has any. The browser
+ * gives one (`webHost`) and tests give one in memory. An app never meets it.
+ */
+export interface Host {
+  readonly storage: Storage;
+  /** The cloud Backend: where its APIs answer, and, for an app with auth,
+   * how a user signs in to it and the sign-in service's own page for
+   * managing accounts. */
+  readonly cloud: {
+    /** What an API's path is resolved against. */
+    readonly url: string;
+    readonly signIn?: Layer.Layer<SignIn>;
+    readonly manageAccounts?: () => Promise<void>;
+  };
+  /** When the app is online and in view. */
+  readonly lifecycle: {
+    readonly online: () => boolean;
+    /** Calls `changed` whenever the network comes or goes. */
+    readonly onOnlineChange: (changed: () => void) => () => void;
+    /** Calls `shown` whenever the app comes back into view. */
+    readonly onForeground: (shown: () => void) => () => void;
+    /** The Backend the launch asked for, if any, as `?backend=device` does
+     * on the web. Asked once, at start. */
+    readonly launchBackend: () => Backend | null;
+  };
+  /** The device's other tabs, where there can be more than one. */
+  readonly tabs?: {
+    readonly announce: (message: TabMessage) => void;
+    readonly listen: (heard: (message: TabMessage) => void) => () => void;
+  };
+}
+
+/**
+ * A Host kept in memory, with no network events and no other tabs: for
+ * tests, and for running an app where nothing outlives the process. Its
+ * cloud Sign-in signs nobody in unless `signIn` is given.
+ */
+export const memoryHost = (
+  options: {
+    readonly online?: () => boolean;
+    readonly signIn?: Layer.Layer<SignIn>;
+    readonly url?: string;
+    readonly launchBackend?: Backend | null;
+  } = {},
+): Host => {
+  // One table per database and name, as a real device keeps it.
+  const tables = new Map<string, Layer.Layer<never>>();
+  const table = <Name extends string>(
+    source: TableSource<Name>,
+    database: string,
+  ): Layer.Layer<StdTableService<Name>> => {
+    const key = `${database}/${source.logicalName}`;
+    let kept = tables.get(key);
+    if (kept === undefined) {
+      kept = Memory.make(source as TableDefinition<Name>).layer as never;
+      tables.set(key, kept);
+    }
+    return kept as Layer.Layer<StdTableService<Name>>;
+  };
+  return {
+    storage: {
+      table,
+      broadcaster: keptBroadcasters(() => defaultBroadcaster),
+      // Nothing outlives the process, so there is nothing to list.
+      sync: { ...Sync.memory(), list: async () => [], remove: async () => {} },
+    },
+    cloud: {
+      url: options.url ?? 'http://localhost',
+      signIn: options.signIn ?? signIn.named({ choose: Effect.succeed(null) }),
+      manageAccounts: async () => {},
+    },
+    lifecycle: {
+      online: options.online ?? (() => true),
+      onOnlineChange: () => () => {},
+      onForeground: () => () => {},
+      launchBackend: () => options.launchBackend ?? null,
+    },
+  };
+};

package/src/app/host/index.ts

@@ -0,0 +1,10 @@
+export {
+  Backend,
+  backendNamed,
+  type Host,
+  keptBroadcasters,
+  memoryHost,
+  type Storage,
+  type TableSource,
+  type TabMessage,
+} from './host.ts';

package/src/app/index.ts

@@ -0,0 +1,10 @@
+// The Web Platform's door: a web app from one config.
+export {
+  createApp,
+  type RootOptions,
+  type WebAppConfig,
+  type WebAuth,
+  type WebAuthApp,
+  type WebPublicApp,
+} from './app.tsx';
+export type { GateNotice, GateView } from './gate/index.ts';

package/src/app/session/define.ts

@@ -0,0 +1,75 @@
+import { Context, type Effect, Schema, type Scope } from 'effect';
+import type { SubscriptionRef } from 'effect';
+import type { Account } from '@kestack/auth-toolkit/client';
+import type { ApiClients, Apis } from '../apis/index.ts';
+import type { StdSync } from './open.ts';
+import { useOpened, useOpenedStatus } from './react.tsx';
+import type { SessionStatus } from './status.ts';
+
+/** What the Web Platform gives a Session to be built from: the app's APIs
+ * signed as the Account, the user's Std Sync, the Account, and the Session
+ * Status. */
+export interface SessionContext<A extends Apis> {
+  /** Whose Session it is. */
+  readonly account: Account;
+  /** Every API, each call signed with the Account's token. A call still on
+   * its way when the Session closes is interrupted. */
+  readonly apis: ApiClients<A>;
+  /** A Std Sync named for the user, kept where the Backend keeps it: on the
+   * device for the cloud Backend, in memory for the device Backend. Make
+   * its collections; it is disposed with the Session. */
+  readonly sync: StdSync;
+  /** Whether the Account has been confirmed since the Session opened. */
+  readonly status: SubscriptionRef.SubscriptionRef<SessionStatus>;
+}
+
+/** A Session was closed, by an Account Switch, a sign-out or a change of
+ * Backend, while something of it still ran. */
+export class SessionClosed extends Schema.Error<SessionClosed>(
+  '@kestack/web-platform/SessionClosed',
+)({ _tag: Schema.tag('SessionClosed') }) {}
+
+/** Who is open, for Effect code: `yield* session.Service`. */
+export interface SessionOf<S> {
+  readonly '@kestack/web-platform/Session': S;
+}
+
+/** Runs an Effect in the open Session, with its Service provided. Rejects
+ * with its failure, or with SessionClosed if the Session closed first. */
+export type Run<S> = <X, E>(
+  effect: Effect.Effect<X, E, SessionOf<S>>,
+) => Promise<X>;
+
+/**
+ * An app's Session, written once over its APIs: what one Account keeps
+ * while it is active. Give it to `createApp` as `auth.session`; everything
+ * else comes out of it. `Service` reaches it from Effect code, and `use`,
+ * `useRun`, `useStatus` and `useApi` from any screen under `SignedIn`.
+ */
+export const defineSession = <A extends Apis, S>(
+  apis: A,
+  open: (context: SessionContext<A>) => Effect.Effect<S, never, Scope.Scope>,
+) => {
+  const Service = Context.Service<SessionOf<S>, S>(
+    '@kestack/web-platform/Session',
+  );
+  return {
+    apis,
+    open,
+    Service,
+    /** The open Session's value. */
+    use: (): S => useOpened().value as S,
+    /** Runs an Effect in the open Session. */
+    useRun: (): Run<S> => useOpened().run as Run<S>,
+    /** Whether the open Account has been confirmed, live. */
+    useStatus: useOpenedStatus,
+    /** One API's client, signed as the open Account. */
+    useApi: <K extends keyof A & string>(name: K): ApiClients<A>[K] =>
+      useOpened().apis[name] as ApiClients<A>[K],
+  };
+};
+
+/** A Session, as `defineSession` makes it. */
+export type SessionDef<A extends Apis, S> = ReturnType<
+  typeof defineSession<A, S>
+>;

package/src/app/session/index.ts

@@ -0,0 +1,17 @@
+export {
+  defineSession,
+  type Run,
+  SessionClosed,
+  type SessionContext,
+  type SessionDef,
+  type SessionOf,
+} from './define.ts';
+export { keepSyncs, syncName } from './keeper.ts';
+export { type Opened, openSession, type StdSync } from './open.ts';
+export {
+  OpenSessionProvider,
+  useOpened,
+  useOpenedOrNone,
+  useOpenedStatus,
+} from './react.tsx';
+export { makeStatus, type SessionStatus, type StatusCell } from './status.ts';

package/src/app/session/keeper.ts

@@ -0,0 +1,34 @@
+const PREFIX = 'user-';
+
+// Std Sync keeps a name lowercase, with a dash for anything else.
+const normalize = (name: string) =>
+  name
+    .normalize('NFD')
+    .replace(/\p{M}+/gu, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+
+/** The name of one user's Std Sync on this device, which `createApp` gives
+ * their Session, so what it keeps is deleted once they sign out. */
+export const syncName = (userId: string) => normalize(`${PREFIX}${userId}`);
+
+/**
+ * Keeps the Std Sync of every user still signed in, deletes every other
+ * user's, and says which it deleted. Only names `syncName` makes are
+ * touched; whatever else the device keeps under Std Sync is left alone.
+ */
+export const keepSyncs = async (
+  userIds: ReadonlyArray<string>,
+  sync: {
+    readonly list: () => Promise<ReadonlyArray<{ readonly name: string }>>;
+    readonly remove: (name: string) => Promise<void>;
+  },
+) => {
+  const kept = new Set(userIds.map(syncName));
+  const gone = (await sync.list())
+    .map(({ name }) => name)
+    .filter((name) => name.startsWith(PREFIX) && !kept.has(name));
+  await Promise.all(gone.map((name) => sync.remove(name)));
+  return gone;
+};

package/src/app/session/open.ts

@@ -0,0 +1,207 @@
+import {
+  Cause,
+  Context,
+  Deferred,
+  Effect,
+  Exit,
+  Layer,
+  ManagedRuntime,
+  Option,
+  type Scope,
+  Stream,
+} from 'effect';
+import { type RpcClient, RpcClient as Client } from 'effect/rpc';
+import type { Account } from '@kestack/auth-toolkit/client';
+import { Authz } from '@kestack/auth-toolkit/guard';
+import { Rpc } from '@kestack/rpc-toolkit/rpc';
+import {
+  createStdSync,
+  type EffectRuntime,
+  type SyncStore,
+} from '@kestack/std-toolkit/sync';
+import type { ApiClients, Apis } from '../apis/index.ts';
+import type { SessionContext } from './define.ts';
+import { SessionClosed } from './define.ts';
+import { syncName } from './keeper.ts';
+import type { StatusCell } from './status.ts';
+
+const makeSync = (
+  name: string,
+  runtime: EffectRuntime<never>,
+  store: SyncStore,
+) => createStdSync<never>({ name, runtime, store });
+
+/** One Account's Std Sync, named for its user. */
+export type StdSync = ReturnType<typeof makeSync>;
+
+/** An open Session as the Web Platform holds it: the app's value, the APIs
+ * signed as the Account, how to run an Effect in it, and its status. */
+export interface Opened<S> {
+  readonly value: S;
+  readonly apis: Readonly<Record<string, unknown>>;
+  readonly run: (
+    effect: Effect.Effect<unknown, unknown, never>,
+  ) => Promise<unknown>;
+  readonly status: StatusCell;
+}
+
+interface ClientOf {
+  readonly '@kestack/web-platform/ApiClient': unique symbol;
+}
+
+type AnyCall = (...args: ReadonlyArray<unknown>) => unknown;
+
+// One API's client, and its WebSocket connection if it has one.
+interface Made {
+  readonly client: object;
+  readonly connection: Option.Option<Rpc.websocket.connection['Service']>;
+}
+
+// Done once a connection that was up goes down: a stream on it is stranded
+// then, as nothing it was sent survives the server's side of the socket.
+const droppedOn = (connection: Made['connection']) =>
+  Option.match(connection, {
+    onNone: () => Effect.never,
+    onSome: ({ connectionStatus }) =>
+      connectionStatus.pipe(
+        Stream.dropWhile((status) => status !== 'connected'),
+        Stream.filter((status) => status !== 'connected'),
+        Stream.runHead,
+        Effect.asVoid,
+      ),
+  });
+
+/**
+ * Opens one Account's Session: a runtime holding every API's client, each
+ * over its own protocol and signed with `token`, the user's Std Sync on
+ * `store`, and then the app's own Session on them. Ends, in order: the
+ * app's Session, the Std Sync once its writes on their way have landed,
+ * every call still in flight (interrupted), the runtime.
+ */
+export const openSession = <A extends Apis, S>(options: {
+  readonly apis: A;
+  readonly protocols: {
+    readonly [K in keyof A]: Layer.Layer<RpcClient.Protocol>;
+  };
+  readonly store: SyncStore;
+  readonly account: Account;
+  readonly token: Effect.Effect<string>;
+  readonly status: StatusCell;
+  readonly open: (
+    context: SessionContext<A>,
+  ) => Effect.Effect<S, never, Scope.Scope>;
+  /** The Session's Service, provided to everything `run` runs. */
+  readonly service: Context.Key<unknown, S>;
+}): Effect.Effect<Opened<S>, never, Scope.Scope> =>
+  Effect.gen(function* () {
+    const { apis, account } = options;
+    const names = Object.keys(apis);
+    const keys = new Map(
+      names.map((name) => [
+        name,
+        Context.Service<ClientOf, Made>(
+          `@kestack/web-platform/ApiClient/${name}`,
+        ),
+      ]),
+    );
+    const bearer = Authz.bearer(options.token);
+    const layers = names.map((name) =>
+      Layer.effect(
+        keys.get(name)!,
+        Effect.all({
+          client: Client.make(apis[name]!.group),
+          connection: Effect.serviceOption(Rpc.websocket.connection),
+        }),
+      ).pipe(Layer.provide([options.protocols[name]!, bearer])),
+    );
+    const runtime = ManagedRuntime.make(
+      (layers.length === 0
+        ? Layer.empty
+        : Layer.mergeAll(
+            ...(layers as [Layer.Layer<ClientOf>]),
+          )) as Layer.Layer<ClientOf>,
+    );
+    yield* Effect.addFinalizer(() => Effect.promise(() => runtime.dispose()));
+    const raw = yield* Effect.promise(() =>
+      runtime.runPromise(
+        Effect.forEach(names, (name) =>
+          Effect.gen(function* () {
+            return yield* keys.get(name)!;
+          }),
+        ),
+      ),
+    );
+
+    // Added before the Std Sync's, so it runs after: the Std Sync's last
+    // writes still land, and only then is a call still in flight cut off.
+    const closed = yield* Deferred.make<void>();
+    yield* Effect.addFinalizer(() => Deferred.succeed(closed, undefined));
+    const cut = <X, E, R>(call: Effect.Effect<X, E, R>) =>
+      Effect.raceFirst(
+        call,
+        Effect.andThen(Deferred.await(closed), Effect.interrupt),
+      );
+    // A stream ends when the Session closes, and when its socket drops, so
+    // whoever reads it opens it again from where they have got to.
+    const signed = ({ client, connection }: Made) =>
+      Object.fromEntries(
+        Object.entries(client).map(([tag, call]) => [
+          tag,
+          typeof call !== 'function'
+            ? call
+            : (...args: ReadonlyArray<unknown>) => {
+                const made = (call as AnyCall)(...args);
+                return Effect.isEffect(made)
+                  ? cut(made)
+                  : Stream.isStream(made)
+                    ? Stream.interruptWhen(
+                        made,
+                        Effect.raceFirst(
+                          Deferred.await(closed),
+                          droppedOn(connection),
+                        ),
+                      )
+                    : made;
+              },
+        ]),
+      );
+    const clients = Object.fromEntries(
+      names.map((name, index) => [name, signed(raw[index] as Made)]),
+    ) as ApiClients<A>;
+
+    const sync = makeSync(syncName(account.user.id), runtime, options.store);
+    yield* Effect.addFinalizer(() =>
+      Effect.tryPromise(() => sync.dispose()).pipe(
+        Effect.catch((error) => Effect.logWarning('[sync]', error)),
+      ),
+    );
+
+    const value = yield* options.open({
+      account,
+      apis: clients,
+      sync,
+      status: options.status.ref,
+    });
+
+    const run = (effect: Effect.Effect<unknown, unknown, never>) =>
+      Deferred.isDoneUnsafe(closed)
+        ? Promise.reject(new SessionClosed())
+        : runtime
+            .runPromiseExit(
+              cut(
+                Effect.provideService(
+                  effect as Effect.Effect<unknown, unknown, unknown>,
+                  options.service,
+                  value,
+                ) as Effect.Effect<unknown, unknown, never>,
+              ),
+            )
+            .then((exit) => {
+              if (Exit.isSuccess(exit)) return exit.value;
+              if (Cause.hasInterruptsOnly(exit.cause))
+                throw new SessionClosed();
+              throw Cause.squash(exit.cause);
+            });
+
+    return { value, apis: clients, run, status: options.status };
+  });

package/src/app/session/react.tsx

@@ -0,0 +1,38 @@
+import {
+  createContext,
+  type ReactNode,
+  useContext,
+  useSyncExternalStore,
+} from 'react';
+import type { Opened } from './open.ts';
+import type { SessionStatus } from './status.ts';
+
+// The open Session, for whatever reads it under `SignedIn`: one per page,
+// as one app runs per page.
+const OpenSession = createContext<Opened<unknown> | undefined>(undefined);
+
+/** Gives the open Session to everything inside. `SignedIn` renders it. */
+export function OpenSessionProvider(props: {
+  readonly opened: Opened<unknown>;
+  readonly children: ReactNode;
+}) {
+  return <OpenSession value={props.opened}>{props.children}</OpenSession>;
+}
+
+/** The open Session; only inside `SignedIn`. */
+export const useOpened = (): Opened<unknown> => {
+  const opened = useContext(OpenSession);
+  if (opened === undefined)
+    throw new Error('A Session is only open inside SignedIn');
+  return opened;
+};
+
+/** The open Session's status, live; only inside `SignedIn`. */
+export const useOpenedStatus = (): SessionStatus => {
+  const { status } = useOpened();
+  return useSyncExternalStore(status.subscribe, status.get, status.get);
+};
+
+/** The open Session, or undefined outside `SignedIn`. */
+export const useOpenedOrNone = (): Opened<unknown> | undefined =>
+  useContext(OpenSession);

package/src/app/session/status.ts

@@ -0,0 +1,46 @@
+import { Effect, SubscriptionRef } from 'effect';
+
+/**
+ * Whether the open Account has been confirmed by its Sign-in since the
+ * Session opened, and when it last was. An Account opened from what the
+ * device remembers is `verifying` until the Sign-in answers; a call made
+ * meanwhile waits for the token, and nothing fails for being early.
+ */
+export interface SessionStatus {
+  readonly state: 'verifying' | 'verified';
+  readonly lastVerifiedAt: Date | null;
+}
+
+/** One Session's status: a SubscriptionRef for Effect code, and a plain
+ * read and subscription for React. The Gate sets it. */
+export interface StatusCell {
+  readonly ref: SubscriptionRef.SubscriptionRef<SessionStatus>;
+  readonly get: () => SessionStatus;
+  readonly subscribe: (changed: () => void) => () => void;
+  readonly set: (status: SessionStatus) => void;
+}
+
+/** A status cell starting at `initial`. */
+export const makeStatus = (initial: SessionStatus): Effect.Effect<StatusCell> =>
+  Effect.map(SubscriptionRef.make(initial), (ref) => {
+    let current = initial;
+    const listeners = new Set<() => void>();
+    return {
+      ref,
+      get: () => current,
+      subscribe: (changed) => {
+        listeners.add(changed);
+        return () => void listeners.delete(changed);
+      },
+      set: (status) => {
+        if (
+          status.state === current.state &&
+          status.lastVerifiedAt?.getTime() === current.lastVerifiedAt?.getTime()
+        )
+          return;
+        current = status;
+        Effect.runSync(SubscriptionRef.set(ref, status));
+        listeners.forEach((changed) => changed());
+      },
+    };
+  });