@oomol-lab/open-flow 0.1.0-beta.89 → 0.1.0-beta.90

package/dist/render/node/licenses.md

@@ -2,6 +2,30 @@
 
 The app bundles dependencies which contain the following licenses:
 
+## @babel/parser - 8.0.4 (MIT)
+
+Copyright (C) 2012-2014 by various contributors (see AUTHORS)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+## @cfworker/json-schema - 4.1.1 (MIT)
+
 ## @wopjs/cast - 0.1.16 (MIT)
 
 MIT License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oomol-lab/open-flow",
-  "version": "0.1.0-beta.89",
+  "version": "0.1.0-beta.90",
   "description": "TypeScript contracts and Browser runtime for Open Flow.",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {
@@ -25,6 +25,10 @@
       "types": "./dist/common/decision.d.ts",
       "import": "./dist/common/decision.js"
     },
+    "./provider-icons": {
+      "types": "./dist/common/provider-icons.d.ts",
+      "import": "./dist/common/provider-icons.js"
+    },
     "./flow-state": {
       "types": "./dist/common/flow-state.d.ts",
       "import": "./dist/common/flow-state.js"

package/src/base/common/cache.ts

@@ -0,0 +1,8 @@
+import type { JsonValue } from '../../types/index.ts'
+
+/** Storage is host-owned. Keys and JSON records are opaque to the delegate. */
+export interface CacheDelegate {
+  get(key: string): Promise<unknown>
+  set(key: string, value: JsonValue): Promise<void>
+  delete(key: string): Promise<void>
+}

package/src/connector/common/providerIconCache.ts

@@ -0,0 +1,191 @@
+import type { CacheDelegate } from '../../base/common/cache.ts'
+
+export type { CacheDelegate } from '../../base/common/cache.ts'
+
+export type ProviderIconRequest =
+  | { readonly kind: 'sprite'; readonly theme: 'light' | 'dark'; readonly url: string; readonly version: string }
+  | { readonly kind: 'image'; readonly providerId: string; readonly url: string }
+
+export interface ProviderIconCacheOptions {
+  /** Non-secret identity of the artwork source or deployment. */
+  readonly scope: string
+  /** Defaults to instance-local memory. Records contain base64 image bytes. */
+  readonly delegate?: CacheDelegate
+  readonly mode?: 'default' | 'refresh' | 'offline'
+  readonly fetch?: typeof fetch
+}
+
+export interface ProviderIconReadOptions {
+  /** Restricts this read even if another caller is loading the same resource online. */
+  readonly allowNetwork?: boolean
+}
+
+/** The browser renderer can consume the same interface over a Node bridge. */
+export interface ProviderIconLoader {
+  get(request: ProviderIconRequest, options?: ProviderIconReadOptions): Promise<string>
+}
+
+interface CachedIcon {
+  readonly formatVersion: 1
+  readonly sourceUrl: string
+  readonly spriteVersion: string | null
+  readonly contentType: string
+  readonly body: string
+  readonly etag: string | null
+  readonly validatedAt: number
+  /** Null means immutable artwork identified by a sprite version. */
+  readonly maxAgeMs: number | null
+}
+
+const defaultMaxAgeMs = 24 * 60 * 60 * 1000
+const dataUrl = (entry: CachedIcon) => `data:${entry.contentType};base64,${entry.body}`
+
+function decodeRecord(value: unknown): CachedIcon | undefined {
+  if (value == null || typeof value !== 'object') return
+  const v = value as CachedIcon
+  if (
+    v.formatVersion !== 1 ||
+    typeof v.sourceUrl !== 'string' ||
+    !(v.spriteVersion === null || typeof v.spriteVersion === 'string') ||
+    typeof v.contentType !== 'string' ||
+    !/^image\/[\w.+-]+$/i.test(v.contentType) ||
+    typeof v.body !== 'string' ||
+    !v.body ||
+    v.body.length % 4 !== 0 ||
+    !/^[A-Za-z0-9+/]*={0,2}$/.test(v.body) ||
+    !(v.etag === null || typeof v.etag === 'string') ||
+    !Number.isFinite(v.validatedAt) ||
+    v.validatedAt < 0 ||
+    !(v.maxAgeMs === null || (Number.isFinite(v.maxAgeMs) && v.maxAgeMs >= 0))
+  )
+    return
+  return v
+}
+
+function encodeBytes(bytes: Uint8Array): string {
+  let text = ''
+  for (let index = 0; index < bytes.length; index += 8192) text += String.fromCharCode(...bytes.subarray(index, index + 8192))
+  return btoa(text)
+}
+
+function freshness(response: Response, immutable: boolean, previous?: CachedIcon): number | null {
+  const control = response.headers.get('cache-control') ?? ''
+  if (/\bno-cache\b/i.test(control)) return 0
+  if (immutable) return null
+  const maxAge = /(?:^|,)\s*max-age\s*=\s*"?(\d+)/i.exec(control)
+  if (maxAge) return Math.max(0, Number(maxAge[1]) * 1000 - (Number(response.headers.get('age')) || 0) * 1000)
+  const expires = Date.parse(response.headers.get('expires') ?? '')
+  if (Number.isFinite(expires)) return Math.max(0, expires - Date.parse(response.headers.get('date') ?? new Date().toUTCString()))
+  return previous?.maxAgeMs ?? defaultMaxAgeMs
+}
+
+/** Complete image responses in bounded, identity-checked slots; no catalog entities live here. */
+export class ProviderIconCache implements ProviderIconLoader {
+  readonly #memory = new Map<string, CachedIcon | undefined>()
+  readonly #pending = new Map<string, Promise<string>>()
+  readonly #targets = new Map<string, string>()
+  readonly #writes = new Map<string, Promise<void>>()
+
+  constructor(private readonly options: ProviderIconCacheOptions) {
+    if (!options.scope.trim()) throw new TypeError('Provider icon cache scope must be nonempty.')
+  }
+
+  get(request: ProviderIconRequest, options: ProviderIconReadOptions = {}): Promise<string> {
+    if (request.url.startsWith('data:image/')) return Promise.resolve(request.url)
+    let protocol: string
+    try {
+      protocol = new URL(request.url).protocol
+    } catch (error) {
+      return Promise.reject(error)
+    }
+    if (!['http:', 'https:'].includes(protocol)) return Promise.reject(new TypeError('Unsupported Provider icon URL.'))
+    const slot = JSON.stringify([
+      'open-flow:provider-icons',
+      1,
+      this.options.scope,
+      request.kind,
+      request.kind === 'sprite' ? request.theme : request.providerId,
+    ])
+    const version = request.kind === 'sprite' ? request.version : null
+    const identity = JSON.stringify([request.url, version])
+    const offline = options.allowNetwork === false || this.options.mode === 'offline'
+    const key = JSON.stringify([slot, identity, offline])
+    const pending = this.#pending.get(key)
+    if (pending) return pending
+    if (!offline) this.#targets.set(slot, identity)
+    const promise = this.#load(slot, identity, request.url, version, offline).finally(() => this.#pending.delete(key))
+    this.#pending.set(key, promise)
+    return promise
+  }
+
+  async #read(slot: string, url: string, version: string | null): Promise<CachedIcon | undefined> {
+    const memory = this.#memory.get(slot)
+    if (this.#memory.has(slot) && (!memory || (memory.sourceUrl === url && memory.spriteVersion === version))) return memory
+    if (!this.options.delegate) return this.#memory.get(slot)
+    try {
+      const stored = await this.options.delegate.get(slot)
+      if (stored === undefined) return this.#memory.get(slot)
+      const entry = decodeRecord(stored)
+      if (entry) {
+        this.#memory.set(slot, entry)
+        return entry
+      }
+      this.#memory.delete(slot)
+      await this.options.delegate.delete(slot)
+    } catch {
+      return this.#memory.get(slot)
+    }
+  }
+
+  async #store(slot: string, identity: string, entry: CachedIcon | undefined): Promise<void> {
+    const operation = (this.#writes.get(slot) ?? Promise.resolve()).then(async () => {
+      if (this.#targets.get(slot) !== identity) return
+      this.#memory.set(slot, entry)
+      if (!this.options.delegate) return
+      try {
+        if (entry) await this.options.delegate.set(slot, { ...entry })
+        else await this.options.delegate.delete(slot)
+      } catch {
+        // Successful image loads survive unavailable or full persistent storage.
+      }
+    })
+    this.#writes.set(slot, operation)
+    try {
+      await operation
+    } finally {
+      if (this.#writes.get(slot) === operation) this.#writes.delete(slot)
+    }
+  }
+
+  async #load(slot: string, identity: string, url: string, version: string | null, offline: boolean): Promise<string> {
+    const stored = await this.#read(slot, url, version)
+    const cached = stored?.sourceUrl === url && stored.spriteVersion === version ? stored : undefined
+    const age = cached == null ? Infinity : Date.now() - cached.validatedAt
+    if (cached && (offline || (this.options.mode !== 'refresh' && age >= 0 && (cached.maxAgeMs === null || age < cached.maxAgeMs)))) return dataUrl(cached)
+    if (offline) throw new Error(`Provider icon is not cached: ${url}`)
+    const response = await (this.options.fetch ?? globalThis.fetch)(url, {
+      credentials: 'omit',
+      referrerPolicy: 'no-referrer',
+      signal: AbortSignal.timeout(15_000),
+      headers: cached?.etag ? { 'if-none-match': cached.etag } : {},
+    })
+    if (response.status !== 304 && !response.ok) throw new Error(`Could not load Provider icon: ${response.status}`)
+    if (response.status === 304 && !cached) throw new Error('Provider icon returned 304 without a cached image.')
+    const contentType = response.status === 304 ? cached!.contentType : response.headers.get('content-type')?.split(';')[0]?.trim().toLowerCase()
+    if (!contentType || !/^image\/[\w.+-]+$/i.test(contentType)) throw new Error('Provider icon response is not an image.')
+    const body = response.status === 304 ? cached!.body : encodeBytes(new Uint8Array(await response.arrayBuffer()))
+    if (!body) throw new Error('Provider icon response is empty.')
+    const entry: CachedIcon = {
+      formatVersion: 1,
+      sourceUrl: url,
+      spriteVersion: version,
+      contentType,
+      body,
+      etag: response.headers.get('etag') ?? (response.status === 304 ? cached!.etag : null),
+      validatedAt: Date.now(),
+      maxAgeMs: freshness(response, version !== null, response.status === 304 ? cached : undefined),
+    }
+    await this.#store(slot, identity, /\bno-store\b/i.test(response.headers.get('cache-control') ?? '') ? undefined : entry)
+    return dataUrl(entry)
+  }
+}

package/src/control/common/api.ts

@@ -1319,9 +1319,15 @@ export class ControlClient {
     }
   }
 
-  async listConnectorProviders(signal?: AbortSignal, flowId?: string, locale?: string): Promise<readonly ConnectorProvider[]> {
+  async listConnectorProviders(
+    signal?: AbortSignal,
+    flowId?: string,
+    locale?: string,
+    options: { readonly cacheOnly?: boolean } = {},
+  ): Promise<readonly ConnectorProvider[]> {
     const query = connectorProvidersQuery(flowId, locale)
-    if (this.catalogCache != null) return (await this.catalogResponse(query, 300_000, signal)).data
+    if (this.catalogCache != null) return (await this.catalogResponse(query, 300_000, signal, false, options.cacheOnly)).data
+    if (options.cacheOnly) throw new ApiError(503, 'catalog.cache-miss', 'No Provider catalog cache is configured.')
     return this.connectorRequest(query.path, 'providers', signal, query.decode)
   }
 
@@ -1695,9 +1701,10 @@ export class ControlClient {
     maxAgeMs: number,
     signal?: AbortSignal,
     fresh = false,
+    cacheOnly = false,
   ) {
     if (this.catalogCache != null)
-      return this.catalogCache.read(query, (etag) => this.readCatalog({ path: query.path, decode: jsonValue }, etag), maxAgeMs, signal, fresh)
+      return this.catalogCache.read(query, (etag) => this.readCatalog({ path: query.path, decode: jsonValue }, etag), maxAgeMs, signal, fresh, cacheOnly)
     const response = await this.readCatalog(query, null, signal)
     if (!response.modified) return invalidResponse()
     return { data: response.data, etag: response.etag }

package/src/control/common/catalogCache.ts

@@ -1,14 +1,10 @@
+import type { CacheDelegate } from '../../base/common/cache.ts'
 import type { JsonValue } from '../../flow/common/change.ts'
 
 import { jsonValue } from './decoding.ts'
 import { ApiError } from './errors.ts'
 
-/** Storage is host-owned. Keys and records are opaque to the delegate. */
-export interface ControlCacheDelegate {
-  get(key: string): Promise<unknown>
-  set(key: string, value: JsonValue): Promise<void>
-  delete(key: string): Promise<void>
-}
+export type ControlCacheDelegate = CacheDelegate
 
 export interface ControlCacheRead {
   readonly path: string
@@ -85,10 +81,15 @@ export class ControlCatalogCache {
       throw new TypeError('Control cache maxAgeMs must be finite and nonnegative.')
   }
 
-  async read<Value>(query: CatalogQuery<Value>, load: CatalogLoad, maxAgeMs: number, signal?: AbortSignal, fresh = false) {
+  async read<Value>(query: CatalogQuery<Value>, load: CatalogLoad, maxAgeMs: number, signal?: AbortSignal, fresh = false, cacheOnly = false) {
     signal?.throwIfAborted()
     const key = JSON.stringify(['open-flow:catalog', 1, this.options.scope, query.path])
-    const result = await wait(this.#request(key, query, load, this.options.maxAgeMs ?? maxAgeMs, fresh || this.options.mode == 'refresh'), signal)
+    const result = await wait(
+      cacheOnly
+        ? this.#load(key, query, load, this.options.maxAgeMs ?? maxAgeMs, false, true)
+        : this.#request(key, query, load, this.options.maxAgeMs ?? maxAgeMs, fresh || this.options.mode == 'refresh'),
+      signal,
+    )
     const data = query.decode(structuredClone(result.body))
     try {
       this.options.onRead?.({ ...result, body: structuredClone(result.body) })
@@ -110,7 +111,14 @@ export class ControlCatalogCache {
     return promise
   }
 
-  async #load<Value>(key: string, query: CatalogQuery<Value>, load: CatalogLoad, maxAgeMs: number, fresh: boolean): Promise<ControlCacheRead> {
+  async #load<Value>(
+    key: string,
+    query: CatalogQuery<Value>,
+    load: CatalogLoad,
+    maxAgeMs: number,
+    fresh: boolean,
+    cacheOnly = false,
+  ): Promise<ControlCacheRead> {
     let cached: CachedResponse | undefined
     try {
       const stored = await this.options.delegate.get(key)
@@ -125,8 +133,8 @@ export class ControlCatalogCache {
     }
     const now = Date.now()
     const stale = cached == null || cached.validatedAt > now || now - cached.validatedAt >= maxAgeMs
-    if (cached != null && (this.options.mode == 'offline' || (!fresh && !stale))) return { ...cached, path: query.path, source: 'cache', stale }
-    if (this.options.mode == 'offline') throw new ApiError(503, 'catalog.cache-miss', `No compatible cached response for ${query.path}.`)
+    if (cached != null && (cacheOnly || this.options.mode == 'offline' || (!fresh && !stale))) return { ...cached, path: query.path, source: 'cache', stale }
+    if (cacheOnly || this.options.mode == 'offline') throw new ApiError(503, 'catalog.cache-miss', `No compatible cached response for ${query.path}.`)
 
     const result = await load(cached?.etag ?? null)
     if (!result.modified && cached == null) throw new ApiError(502, 'response.invalid', 'A catalog returned 304 without a cached response.')