terrier-engine 4.13.6 → 4.14.0

package/data-dive/dives/dive-runs.ts

@@ -2,7 +2,8 @@ import {ModalPart} from "../../terrier/modals"
 import {PartTag} from "tuff-core/parts"
 import {DdDive, DdDiveRun, UnpersistedDdDiveRun} from "../gen/models"
 import Db from "../dd-db"
-import Api, {ErrorEvent} from "../../terrier/api"
+import Api from "../../terrier/api"
+import {ErrorEvent} from "../../terrier/api-subscriber"
 import {Query} from "../queries/queries"
 import {DivTag, HtmlParentTag} from "tuff-core/html"
 import {IconName} from "../../terrier/theme"

package/package.json

@@ -4,7 +4,7 @@
   "files": [
     "*"
   ],
-  "version": "4.13.6",
+  "version": "4.14.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/Terrier-Tech/terrier-engine"

package/terrier/api-subscriber.ts

@@ -0,0 +1,404 @@
+import Api, {ApiResponse, noArgListener, Streamer} from "./api"
+import {LogEntry} from "./logging"
+import dayjs from "dayjs"
+import duration from "dayjs/plugin/duration"
+
+dayjs.extend(duration)
+
+/** Configuration for ApiSubscribers */
+export type SubscriptionOptions = {
+    /** If true, retry the subscription after it is cancelled */
+    keepAlive?: boolean
+}
+
+/** Parameters to send with the subscription request */
+export type SubscriptionParams = Record<string, string>
+
+export type SubscriptionEventHandlers<TResult> = {
+    onResult: resultListener<TResult>[]
+    onError: errorListener[]
+    onLog: logListener[]
+}
+
+export type SubscriptionLifecycleHandlers = {
+    onSubscribe: noArgListener[]
+    onUnsubscribe: noArgListener[]
+    onClose: closeListener[]
+}
+
+type resultListener<TResult> = (result: ResultEvent<TResult>) => boolean
+type errorListener = (result: ErrorEvent) => boolean
+type logListener = (log: LogEvent) => void
+type closeListener = (reason?: string) => void
+
+
+type BaseSubscriptionEvent = {
+    _type: '_result' | '_error' | '_log' | '_close' | undefined
+}
+
+export type SubscriptionEvent<TResult> = BaseSubscriptionEvent & (ResultEvent<TResult> | ErrorEvent | LogEvent | CloseEvent)
+
+/** Type of result events from a subscription */
+export type ResultEvent<TResult> = BaseSubscriptionEvent & { _type: '_result' | undefined } & TResult
+
+/** Type of error events from a subscription */
+export type ErrorEvent = BaseSubscriptionEvent & { _type: '_error' } & {
+    prefix?: string
+    message: string
+    backtrace: string[]
+}
+
+/** Type of log events from a subscription */
+export type LogEvent = BaseSubscriptionEvent & { _type: '_log' } & LogEntry
+
+export type CloseEvent = BaseSubscriptionEvent & { _type: '_close' }
+
+/**
+ * An abstraction over the process of receiving continuous updates from the server.
+ * This allows client code to specify a dependency on continuous updates of a particular type without needing
+ * to care about how those updates are fulfilled.
+ *
+ * Behind the scenes, this could be handled by pulling from the client (PollingSubscriber),
+ * pushing from the server (CableSubscriber), or a hybrid of the two (StreamingSubscriber).
+ *
+ * Subclasses are responsible for implementing the process of initiating and finalizing the subscription and
+ * passing events to the appropriate handlers.
+ *
+ * Each subclass is responsible for providing a constructor with whatever dependencies are required, but all subclasses
+ * must implement `params` and `options` properties and handle them appropriately.
+ */
+export abstract class ApiSubscriber<TResult, TParams extends SubscriptionParams> {
+
+    public abstract params: TParams
+    public abstract options?: SubscriptionOptions
+
+    protected isSubscribed: boolean = false
+
+    protected eventHandlers: SubscriptionEventHandlers<TResult> = { onResult: [], onError: [], onLog: [] }
+    protected lifecycleHandlers: SubscriptionLifecycleHandlers = { onSubscribe: [], onUnsubscribe: [], onClose: [] }
+    protected otherHandlers: Record<string, ((event: unknown) => boolean | void)[]> = {}
+
+    // Handler registration
+
+    /** Register a handler for a custom event type */
+    public on<EventType>(eventType: string, handler: (event: EventType) => boolean | void): this {
+        if (eventType in ['_result', '_error', '_log', '_close']) {
+            throw new Error(`${eventType} is a reserved handler type. Please use a different type or use the appropriate handler registration function.`)
+        }
+
+        this.otherHandlers[eventType] ??= []
+        this.otherHandlers[eventType].push(handler as (event: unknown) => boolean | void)
+        return this
+    }
+
+    /** Register a handler for the default result type of this subscriber */
+    public onResult(handler: (result: ResultEvent<TResult>) => boolean): this {
+        this.eventHandlers.onResult.push(handler)
+        return this
+    }
+
+    /** Register a handler for error events */
+    public onError(handler: (error: ErrorEvent) => boolean): this {
+        this.eventHandlers.onError.push(handler)
+        return this
+    }
+
+    /** Register a handler for log events */
+    public onLog(handler: (logEntry: LogEvent) => void): this {
+        this.eventHandlers.onLog.push(handler)
+        return this
+    }
+
+    /** Register a handler to be notified when this subscriber is subscribed */
+    public onSubscribe(handler: () => void): this {
+        return this.onLifecycle('onSubscribe', handler)
+    }
+
+    /** Register a handler to be notified when this subscriber is manually unsubscribed */
+    public onUnsubscribe(handler: () => void): this {
+        return this.onLifecycle('onUnsubscribe', handler)
+    }
+
+    /** Register a handler to be notified when the publisher source of this subscriber closes the subscription */
+    public onClose(handler: () => void): this {
+        return this.onLifecycle('onClose', handler)
+    }
+
+    /** utility to register a generic lifecycle handler */
+    protected onLifecycle(key: keyof SubscriptionLifecycleHandlers, handler: noArgListener): this
+    protected onLifecycle(key: 'onClose', handler: (reason?: string) => void): this
+    protected onLifecycle(key: keyof SubscriptionLifecycleHandlers, handler: noArgListener | ((reason?: string) => void)): this {
+        this.lifecycleHandlers[key].push(handler)
+        return this
+    }
+
+    // Start or stop subscription
+
+    /**
+     * Starts the subscription. Calling this after the subscription has already been started has no effect
+     */
+    public subscribe(): this {
+        if (this.isSubscribed) return this
+        this.subscribeImpl()
+        this.isSubscribed = true
+        this.notifyLifecycle('onSubscribe')
+        return this
+    }
+
+    /** Stops the subscription and closes the connection. */
+    public unsubscribe(): void {
+        if (!this.isSubscribed) {
+            throw new Error("Can't unsubscribe from a un-started subscription!")
+        }
+        this.unsubscribeImpl()
+        this.isSubscribed = false
+        this.notifyLifecycle('onUnsubscribe')
+    }
+
+    // Modify subscription params
+
+    /** Update the params of this subscriber. Depending on the implementation, this may restart the subscription. */
+    public abstract updateParams(newParams: TParams): void
+
+    // Internal
+
+    protected close() {
+        this.isSubscribed = false
+    }
+
+    /** Call the handlers for the given lifecycle event */
+    protected notifyLifecycle(key: keyof SubscriptionLifecycleHandlers): void
+    protected notifyLifecycle(key: 'onClose', reason: string | undefined): void
+    protected notifyLifecycle(key: keyof SubscriptionLifecycleHandlers, reason: string | undefined = undefined): void {
+        if (key == 'onClose') {
+            this.lifecycleHandlers[key].forEach(handler => handler(reason))
+        } else {
+            this.lifecycleHandlers[key].forEach(handler => handler())
+        }
+    }
+
+    /** Subclasses implement this method to start the subscription */
+    protected abstract subscribeImpl(): void
+
+    /** Subclasses imlpement this method to end the subscription */
+    protected abstract unsubscribeImpl(): void
+}
+
+////////////////////////////////////////////////////////////////////////////////
+// Polling Subscriber
+////////////////////////////////////////////////////////////////////////////////
+
+/**
+ * An implementation of ApiSubscriber that uses polling to periodically make a request to the server
+ */
+export class PollingSubscriber<TResult, TParams extends SubscriptionParams> extends ApiSubscriber<TResult, TParams> {
+
+    // used to ensure we only schedule one interval at a time and allows for cancellation.
+    private timeoutHandle: NodeJS.Timeout | null = null
+
+    /**
+     * @param url the url to make a request to.
+     * @param params params to use to make the request.
+     * @param interval the interval on which to poll. Either a number of milliseconds or a dayjs Duration.
+     * @param options extra subscription options
+     */
+    constructor(
+        public url: string,
+        public params: TParams,
+        public interval: number | duration.Duration,
+        public options: SubscriptionOptions | undefined = undefined
+    ) {
+        super()
+    }
+
+    subscribeImpl() {
+        if (this.timeoutHandle) return
+        this.makeRequest()
+    }
+
+    unsubscribeImpl() {
+        this.clearTimeout()
+    }
+
+    updateParams(newParams: TParams) {
+        this.params = newParams
+        this.makeRequest()
+    }
+
+    private makeRequest() {
+        this.clearTimeout()
+        this.request().then(response => {
+            let shouldContinuePolling = true
+            if ('events' in response) {
+                for (const event of response.events) {
+                    shouldContinuePolling &&= this.handleEvent(event)
+                }
+            } else {
+                if (response.status == 'error') response._type = '_error'
+                shouldContinuePolling = this.handleEvent(response)
+            }
+
+            if (shouldContinuePolling) {
+                this.startTimeout()
+            } else {
+                this.unsubscribe()
+            }
+        })
+    }
+
+    protected request(): Promise<((ApiResponse & SubscriptionEvent<TResult>) | { events: SubscriptionEvent<TResult>[] })> {
+        return Api.get<((ApiResponse & SubscriptionEvent<TResult>) | { events: SubscriptionEvent<TResult>[] })>(this.url, this.params)
+    }
+
+    protected handleEvent(event: SubscriptionEvent<TResult>): boolean {
+        let shouldContinuePolling = true
+
+        switch (event._type) {
+            case '_result':
+            case undefined:
+                for (const handler of this.eventHandlers.onResult) {
+                    const r = handler(event)
+                    shouldContinuePolling &&= r
+                }
+                break
+            case '_error':
+                for (const handler of this.eventHandlers.onError) {
+                    const r = handler(event)
+                    shouldContinuePolling &&= r
+                }
+                break
+            case '_log':
+                this.eventHandlers.onLog.forEach(handler => handler(event))
+                break
+            case '_close':
+                this.notifyLifecycle('onClose')
+                this.close()
+                shouldContinuePolling = this.options?.keepAlive ?? false
+                break
+            default:
+                const otherEvent = event as any
+                for (const handler of this.otherHandlers[otherEvent._type]) {
+                    const r = handler(otherEvent) ?? true
+                    shouldContinuePolling &&= r
+                }
+        }
+
+        return shouldContinuePolling
+    }
+
+    protected clearTimeout() {
+        if (this.timeoutHandle) {
+            clearTimeout(this.timeoutHandle)
+            this.timeoutHandle = null
+        }
+    }
+
+    protected startTimeout() {
+        if (this.timeoutHandle) return
+        const intervalMs = (dayjs.isDuration(this.interval)) ? this.interval.asMilliseconds() : this.interval
+        this.timeoutHandle = setTimeout(this.makeRequest.bind(this), intervalMs)
+    }
+}
+
+////////////////////////////////////////////////////////////////////////////////
+// Action Cable Subscriber
+////////////////////////////////////////////////////////////////////////////////
+
+/**
+ * An ApiSubscriber that uses ActionCable to get pushed results from the server.
+ * Not implemented yet
+ */
+export class CableSubscriber<TResult, TParams extends SubscriptionParams> extends ApiSubscriber<TResult, TParams> {
+
+    constructor(
+        public channelName: string,
+        public params: TParams,
+        public options: SubscriptionOptions | undefined = undefined
+    ) {
+        throw new Error("Method not implemented.")
+        super()
+    }
+
+    public updateParams(_newParams: TParams): void {
+        throw new Error("Method not implemented.")
+    }
+    protected subscribeImpl(): void {
+        throw new Error("Method not implemented.")
+    }
+    protected unsubscribeImpl(): void {
+        throw new Error("Method not implemented.")
+    }
+}
+
+////////////////////////////////////////////////////////////////////////////////
+// Event Stream Subscriber
+////////////////////////////////////////////////////////////////////////////////
+
+export class StreamingSubscriber<TResult, TParams extends SubscriptionParams> extends ApiSubscriber<TResult, TParams> {
+
+    private streamer?: Streamer
+
+    constructor(
+        public url: string,
+        public params: TParams,
+        public options: SubscriptionOptions | undefined = undefined,
+    ) {
+        super()
+    }
+
+    public on<EventType>(eventType: string, handler: (event: EventType) => boolean | void): this {
+        this.streamer?.on(eventType, handler)
+        return super.on(eventType, handler)
+    }
+
+    public onResult(handler: (result: ResultEvent<TResult>) => boolean): this {
+        this.streamer?.on<ResultEvent<TResult>>('_result', handler)
+        return super.onResult(handler)
+    }
+
+    public onError(handler: (error: ErrorEvent) => boolean): this {
+        this.streamer?.on<ErrorEvent>('_error', handler)
+        return super.onError(handler)
+    }
+
+    public onLog(handler: (logEntry: LogEvent) => void): this {
+        this.streamer?.on<LogEvent>('_log', handler)
+        return super.onLog(handler)
+    }
+
+    protected subscribeImpl(): void {
+        const paramsString = new URLSearchParams(this.params).toString()
+        const streamer = new Streamer(`${this.url}?${paramsString}`, this.options ?? {})
+
+        this.eventHandlers.onResult.forEach(handler => streamer.on<ResultEvent<TResult>>('_result', this.wrapHandler(handler)))
+        this.eventHandlers.onError.forEach(handler => streamer.on<ErrorEvent>('_error', this.wrapHandler(handler)))
+        this.eventHandlers.onLog.forEach(handler => streamer.on<LogEvent>('_log', handler))
+        this.lifecycleHandlers.onClose.forEach(handler => streamer.onClose(handler))
+        streamer.onClose(() => {
+            this.close()
+        })
+        Object.entries(this.otherHandlers)
+            .forEach(([key, handlers]) =>
+                handlers.forEach(handler => streamer.on(key, this.wrapHandler(handler)))
+            )
+
+        this.streamer = streamer
+    }
+    protected unsubscribeImpl(): void {
+        this.streamer?.sse.close()
+        this.streamer = undefined
+    }
+
+    public updateParams(newParams: TParams): void {
+        this.unsubscribeImpl()
+        this.params = newParams
+        this.subscribeImpl()
+    }
+
+    private wrapHandler<T>(handler: (param: T) => boolean | void): (param: T) => void {
+        return (param: T) => {
+            const shouldContinue = handler(param) ?? true
+            if (!shouldContinue) this.unsubscribe()
+        }
+    }
+}

package/terrier/api.ts

@@ -1,10 +1,9 @@
 import {Logger} from "tuff-core/logging"
 import {QueryParams} from "tuff-core/urls"
 import {LogEntry} from "./logging"
+import {ErrorEvent} from "./api-subscriber"
 
 const log = new Logger('Api')
-log.level = 'debug'
-
 
 ////////////////////////////////////////////////////////////////////////////////
 // Basic Requests
@@ -79,21 +78,32 @@ async function apiRequest<ResponseType>(url: string, config: RequestInit): Promi
  * @param params a set of parameters that will be added to the URL as a query string
  */
 async function safeGet<ResponseType>(url: string, params: QueryParams | Record<string, string | undefined>): Promise<ResponseType> {
+    const response = await get<ApiResponse & ResponseType>(url, params)
+    if (response.status == 'error') {
+        throw new ApiException(response.message)
+    }
+    return response
+}
+
+/**
+ * Performs a GET request for the given datatype.
+ * Unlike `safeGet`, this will return the result regardless of the response status.
+ * `ResponseType` does not need to include the `status` or `message` fields, this is handled automatically.
+ * @param url the base URL for the request
+ * @param params a set of parameters that will be added to the URL as a query string
+ */
+async function get<ResponseType>(url: string, params: QueryParams | Record<string, string | undefined>): Promise<ResponseType> {
     if (!params.raw) {
         params = new QueryParams(params as Record<string, string>)
     }
     const fullUrl = (params as QueryParams).serialize(url)
-    log.debug(`Safe getting ${fullUrl}`)
-    const response = await apiRequest<ResponseType>(fullUrl, {
+    log.debug(`Getting ${fullUrl}`)
+    return await apiRequest<ResponseType>(fullUrl, {
         method: 'GET',
         headers: {
             'Accept': 'application/json'
         }
     })
-    if (response.status == 'error') {
-        throw new ApiException(response.message)
-    }
-    return response
 }
 
 /**
@@ -142,14 +152,6 @@ async function post<ResponseType>(url: string, body: Record<string, unknown> | F
 // Event Streams
 ////////////////////////////////////////////////////////////////////////////////
 
-/**
- * Type of error events from a streaming response.
- */
-export type ErrorEvent = {
-    prefix?: string
-    message: string
-    backtrace: string[]
-}
 
 /**
  * Configure a `Streamer`.
@@ -158,7 +160,7 @@ export type StreamOptions = {
     keepAlive?: boolean
 }
 
-type noArgListener = () => any
+export type noArgListener = () => any
 
 type StreamLifecycle = 'close'
 
@@ -172,13 +174,13 @@ export class Streamer {
         close: []
     }
 
-    constructor(readonly url: string, readonly options: StreamOptions) {
+    constructor(readonly url: string, readonly options: StreamOptions | undefined = undefined) {
         this.sse = new EventSource(url)
 
         // this is a special event sent by the ResponseStreamer on the server
         // to tell us that the request is done
         this.sse.addEventListener('_close', evt => {
-            if (!this.options.keepAlive) {
+            if (!this.options?.keepAlive) {
                 log.debug(`Closing Streamer at ${url}`, evt)
                 this.sse.close()
                 for (const listener of this.lifecycleListeners['close']) {
@@ -220,11 +222,10 @@ export class Streamer {
 
     onClose(listener: noArgListener) {
         this.lifecycleListeners['close'].push(listener)
+        return this
     }
 }
 
-
-
 /**
  * Creates a streaming response for the given endpoint.
  * @param url
@@ -242,6 +243,7 @@ function stream(url: string, options: StreamOptions={}): Streamer {
 
 const Api = {
     safeGet,
+    get,
     safePost,
     post,
     stream,