terrier-engine 4.14.0 → 4.14.2

package/package.json

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

package/terrier/api-subscriber.ts

@@ -2,6 +2,7 @@ import Api, {ApiResponse, noArgListener, Streamer} from "./api"
 import {LogEntry} from "./logging"
 import dayjs from "dayjs"
 import duration from "dayjs/plugin/duration"
+import {Logger} from "tuff-core/logging";
 
 dayjs.extend(duration)
 
@@ -11,8 +12,14 @@ export type SubscriptionOptions = {
     keepAlive?: boolean
 }
 
+/** Options specific to Subscribers that use GET HTTP requests */
+export type GetSubscriberOptions = {
+    /** If true, keys in the params object will be snakified before being sent to the server */
+    snakifyKeys?: boolean
+}
+
 /** Parameters to send with the subscription request */
-export type SubscriptionParams = Record<string, string>
+export type SubscriptionParams = Record<string, unknown>
 
 export type SubscriptionEventHandlers<TResult> = {
     onResult: resultListener<TResult>[]
@@ -67,10 +74,7 @@ export type CloseEvent = BaseSubscriptionEvent & { _type: '_close' }
  * 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
+export abstract class ApiSubscriber<TResult, TParams extends SubscriptionParams, TOptions extends SubscriptionOptions = SubscriptionOptions> {
 
     protected isSubscribed: boolean = false
 
@@ -78,6 +82,17 @@ export abstract class ApiSubscriber<TResult, TParams extends SubscriptionParams>
     protected lifecycleHandlers: SubscriptionLifecycleHandlers = { onSubscribe: [], onUnsubscribe: [], onClose: [] }
     protected otherHandlers: Record<string, ((event: unknown) => boolean | void)[]> = {}
 
+    /**
+     * @param params   parameters sent with subscription requests to customize server-side behavior
+     * @param options  options that customize client-side behavior of the subscriber
+     * @param logger
+     * @protected
+     */
+    protected constructor(public params: TParams, public options?: TOptions, public logger?: Logger) {
+        this.options ??= {} as TOptions
+        this.logger ??= new Logger(this.constructor.name)
+    }
+
     // Handler registration
 
     /** Register a handler for a custom event type */
@@ -147,9 +162,7 @@ export abstract class ApiSubscriber<TResult, TParams extends SubscriptionParams>
 
     /** Stops the subscription and closes the connection. */
     public unsubscribe(): void {
-        if (!this.isSubscribed) {
-            throw new Error("Can't unsubscribe from a un-started subscription!")
-        }
+        if (!this.isSubscribed) return
         this.unsubscribeImpl()
         this.isSubscribed = false
         this.notifyLifecycle('onUnsubscribe')
@@ -170,6 +183,7 @@ export abstract class ApiSubscriber<TResult, TParams extends SubscriptionParams>
     protected notifyLifecycle(key: keyof SubscriptionLifecycleHandlers): void
     protected notifyLifecycle(key: 'onClose', reason: string | undefined): void
     protected notifyLifecycle(key: keyof SubscriptionLifecycleHandlers, reason: string | undefined = undefined): void {
+        this.logNotification(key, reason)
         if (key == 'onClose') {
             this.lifecycleHandlers[key].forEach(handler => handler(reason))
         } else {
@@ -177,10 +191,47 @@ export abstract class ApiSubscriber<TResult, TParams extends SubscriptionParams>
         }
     }
 
+    protected notifyResult(event: ResultEvent<TResult>) {
+        this.logNotification('_result', event)
+        const shouldContinue = this.eventHandlers.onResult
+            .map(handler => handler(event))
+            .every(b => b)
+        if (!shouldContinue) this.unsubscribe()
+    }
+
+    protected notifyError(event: ErrorEvent) {
+        this.logNotification('_error', event)
+        const shouldContinue = this.eventHandlers.onError
+            .map(handler => handler(event))
+            .every(b => b)
+        if (!shouldContinue) this.unsubscribe()
+    }
+
+    protected notifyLog(event: LogEvent) {
+        this.logNotification('_log', event)
+        this.eventHandlers.onLog.forEach(handler => handler(event))
+    }
+
+    protected notifyOther(key: string, event: any) {
+        this.logNotification(key, event)
+        const shouldContinue = this.otherHandlers[key]
+            .map(handler => handler(event) !== false)
+            .every(b => b)
+        if (!shouldContinue) this.unsubscribe()
+    }
+
+    protected logNotification(key: string, event: any) {
+        if (event === undefined) {
+            this.logger?.debug('notify', key)
+        } else {
+            this.logger?.debug('notify', key, event)
+        }
+    }
+
     /** Subclasses implement this method to start the subscription */
     protected abstract subscribeImpl(): void
 
-    /** Subclasses imlpement this method to end the subscription */
+    /** Subclasses implement this method to end the subscription */
     protected abstract unsubscribeImpl(): void
 }
 
@@ -188,10 +239,12 @@ export abstract class ApiSubscriber<TResult, TParams extends SubscriptionParams>
 // Polling Subscriber
 ////////////////////////////////////////////////////////////////////////////////
 
+type PollingResponse<TResult> = (ApiResponse & SubscriptionEvent<TResult>) | { events: SubscriptionEvent<TResult>[] }
+
 /**
  * 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> {
+export class PollingSubscriber<TResult, TParams extends SubscriptionParams> extends ApiSubscriber<TResult, TParams, (SubscriptionOptions & GetSubscriberOptions)> {
 
     // used to ensure we only schedule one interval at a time and allows for cancellation.
     private timeoutHandle: NodeJS.Timeout | null = null
@@ -201,14 +254,16 @@ export class PollingSubscriber<TResult, TParams extends SubscriptionParams> exte
      * @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
+     * @param logger a specific logger to use
      */
     constructor(
         public url: string,
-        public params: TParams,
         public interval: number | duration.Duration,
-        public options: SubscriptionOptions | undefined = undefined
+        params: TParams,
+        options?: (SubscriptionOptions & GetSubscriberOptions),
+        logger?: Logger
     ) {
-        super()
+        super(params, options, logger)
     }
 
     subscribeImpl() {
@@ -228,62 +283,49 @@ export class PollingSubscriber<TResult, TParams extends SubscriptionParams> exte
     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)
+                   this.handleEvent(event)
                 }
             } else {
                 if (response.status == 'error') response._type = '_error'
-                shouldContinuePolling = this.handleEvent(response)
+                this.handleEvent(response)
             }
 
-            if (shouldContinuePolling) {
-                this.startTimeout()
-            } else {
-                this.unsubscribe()
-            }
+            this.startTimeout()
         })
     }
 
-    protected request(): Promise<((ApiResponse & SubscriptionEvent<TResult>) | { events: SubscriptionEvent<TResult>[] })> {
-        return Api.get<((ApiResponse & SubscriptionEvent<TResult>) | { events: SubscriptionEvent<TResult>[] })>(this.url, this.params)
-    }
+    protected async request(): Promise<PollingResponse<TResult>> {
+        const params = Api.objectToQueryParams(this.params, this.options?.snakifyKeys)
 
-    protected handleEvent(event: SubscriptionEvent<TResult>): boolean {
-        let shouldContinuePolling = true
+        // Add _polling param so that the server-side can adjust behavior based on whether it is being polled or requested normally.
+        params._polling = true.toString()
+        const result = await Api.get<PollingResponse<TResult>>(this.url, params);
+        this.logger?.debug("polling request", params, result)
+        return result
+    }
 
+    protected handleEvent(event: SubscriptionEvent<TResult>) {
         switch (event._type) {
             case '_result':
             case undefined:
-                for (const handler of this.eventHandlers.onResult) {
-                    const r = handler(event)
-                    shouldContinuePolling &&= r
-                }
+                this.notifyResult(event)
                 break
             case '_error':
-                for (const handler of this.eventHandlers.onError) {
-                    const r = handler(event)
-                    shouldContinuePolling &&= r
-                }
+                this.notifyError(event)
                 break
             case '_log':
-                this.eventHandlers.onLog.forEach(handler => handler(event))
+                this.notifyLog(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
-                }
+                this.notifyOther(otherEvent._type, otherEvent)
         }
-
-        return shouldContinuePolling
     }
 
     protected clearTimeout() {
@@ -294,8 +336,12 @@ export class PollingSubscriber<TResult, TParams extends SubscriptionParams> exte
     }
 
     protected startTimeout() {
+        if (!this.isSubscribed) return
         if (this.timeoutHandle) return
         const intervalMs = (dayjs.isDuration(this.interval)) ? this.interval.asMilliseconds() : this.interval
+
+        this.logger?.debug("polling in", intervalMs, "milliseconds")
+
         this.timeoutHandle = setTimeout(this.makeRequest.bind(this), intervalMs)
     }
 }
@@ -312,11 +358,12 @@ export class CableSubscriber<TResult, TParams extends SubscriptionParams> extend
 
     constructor(
         public channelName: string,
-        public params: TParams,
-        public options: SubscriptionOptions | undefined = undefined
+        params: TParams,
+        options?: SubscriptionOptions,
+        logger?: Logger,
     ) {
         throw new Error("Method not implemented.")
-        super()
+        super(params, options, logger)
     }
 
     public updateParams(_newParams: TParams): void {
@@ -334,71 +381,59 @@ export class CableSubscriber<TResult, TParams extends SubscriptionParams> extend
 // Event Stream Subscriber
 ////////////////////////////////////////////////////////////////////////////////
 
-export class StreamingSubscriber<TResult, TParams extends SubscriptionParams> extends ApiSubscriber<TResult, TParams> {
+export class StreamingSubscriber<TResult, TParams extends SubscriptionParams> extends ApiSubscriber<TResult, TParams, (SubscriptionOptions & GetSubscriberOptions)> {
 
     private streamer?: Streamer
 
     constructor(
         public url: string,
-        public params: TParams,
-        public options: SubscriptionOptions | undefined = undefined,
+        params: TParams,
+        options?: (SubscriptionOptions & GetSubscriberOptions),
+        logger?: Logger
     ) {
-        super()
+        super(params, options, logger)
     }
 
     public on<EventType>(eventType: string, handler: (event: EventType) => boolean | void): this {
-        this.streamer?.on(eventType, handler)
+        if (!(eventType in this.otherHandlers) && this.streamer) {
+            this.listenOther(eventType, this.streamer)
+        }
         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)
+    public updateParams(newParams: TParams): void {
+        this.unsubscribeImpl()
+        this.params = newParams
+        this.subscribeImpl()
     }
 
     protected subscribeImpl(): void {
-        const paramsString = new URLSearchParams(this.params).toString()
+        const params = Api.objectToQueryParams(this.params, this.options?.snakifyKeys)
+        const paramsString = new URLSearchParams(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()
+        streamer
+            .on<ResultEvent<TResult>>('_result', this.notifyResult.bind(this))
+            .on<ErrorEvent>('_error', this.notifyError.bind(this))
+            .on<LogEvent>('_log', this.notifyLog.bind(this))
+            .onClose(() => {
+                this.close()
+                this.notifyLifecycle('onClose')
+            })
+
+        Object.keys(this.otherHandlers).forEach(key => {
+            this.listenOther(key, streamer)
         })
-        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()
-        }
+    protected listenOther(key: string, streamer: Streamer) {
+        streamer.on(key, (event) => this.notifyOther(key, event))
     }
-}
+}

package/terrier/api.ts

@@ -2,6 +2,8 @@ import {Logger} from "tuff-core/logging"
 import {QueryParams} from "tuff-core/urls"
 import {LogEntry} from "./logging"
 import {ErrorEvent} from "./api-subscriber"
+import Strings from "tuff-core/strings";
+import dayjs from "dayjs";
 
 const log = new Logger('Api')
 
@@ -147,6 +149,28 @@ async function post<ResponseType>(url: string, body: Record<string, unknown> | F
     return await request<ResponseType & ApiResponse>(url, config)
 }
 
+////////////////////////////////////////////////////////////////////////////////
+// Query Params
+////////////////////////////////////////////////////////////////////////////////
+
+/**
+ * Transforms the given object to a QueryParams compatible object.
+ */
+function objectToQueryParams(object: Record<string, unknown>, snakifyKeys: boolean = false): Record<string, string> {
+    const raw: Record<string, string> = {}
+    for (const [key, value] of Object.entries(object)) {
+        const paramKey = snakifyKeys ? Strings.splitWords(key).map(w => w.toLowerCase()).join("_") : key
+
+        if (dayjs.isDayjs(value)) {
+            raw[paramKey] = value.format()
+        } else if (value == undefined) {
+            raw[paramKey] = ""
+        } else {
+            raw[paramKey] = value?.toString()
+        }
+    }
+    return raw
+}
 
 ////////////////////////////////////////////////////////////////////////////////
 // Event Streams
@@ -248,5 +272,6 @@ const Api = {
     post,
     stream,
     addRequestDecorator,
+    objectToQueryParams,
 }
 export default Api