@dronedeploy/rocos-js-sdk 3.0.0-alpha.19 → 3.0.0-alpha.20

package/helpers/callerMessageHelpers.d.ts

@@ -0,0 +1,14 @@
+import { IRocosCallerMessage, IRocosCallerMessageChunk, IRocosCallerMessageResponse } from '../models';
+import { OperatorFunction } from 'rxjs';
+/** Given a caller message, return the responses contained within it.
+ *
+ * Chunked responses with acks and results will return the intermediate acks and results as Responses along with the chunk itself
+ */
+export declare function getResponses(res: IRocosCallerMessage): (IRocosCallerMessageResponse | IRocosCallerMessageChunk)[];
+/** A pipeable operator that will convert a stream of chunks into a stream of responses.
+ *
+ * Any non-chunk messages will be passed through unchanged.
+ *
+ * Chunked responses will be buffered until all chunks are received, then merged into a single response.
+ */
+export declare function handleChunkedMessages(): OperatorFunction<IRocosCallerMessageChunk | IRocosCallerMessageResponse, IRocosCallerMessageResponse>;

package/helpers/callerMessageHelpers.js

@@ -0,0 +1,86 @@
+import { map, pipe } from 'rxjs';
+import { filter } from 'rxjs/operators';
+/** Given a caller message, return the responses contained within it.
+ *
+ * Chunked responses with acks and results will return the intermediate acks and results as Responses along with the chunk itself
+ */
+export function getResponses(res) {
+    if (res.chunks?.chunks) {
+        return getIntermediateResponsesFromChunks(res.chunks.chunks);
+    }
+    if (res.responses?.responses) {
+        return res.responses.responses;
+    }
+    return [];
+}
+/** Given a list of chunks, convert any intermediate acks and results into responses. */
+function getIntermediateResponsesFromChunks(chunks) {
+    const responses = [];
+    for (const chunk of chunks) {
+        // chunk needs to be pushed first so that the final response can be constructed from the chunks
+        // before any result message can close the observable
+        responses.push(chunk);
+        if (chunk.uid && (chunk.ack || chunk.result)) {
+            responses.push({
+                uid: chunk.uid,
+                ack: chunk.ack,
+                result: chunk.result,
+            });
+        }
+    }
+    return responses;
+}
+/** A pipeable operator that will convert a stream of chunks into a stream of responses.
+ *
+ * Any non-chunk messages will be passed through unchanged.
+ *
+ * Chunked responses will be buffered until all chunks are received, then merged into a single response.
+ */
+export function handleChunkedMessages() {
+    let chunkBuffer = null;
+    return pipe(map((message) => {
+        if ('chunkIndex' in message) {
+            if (chunkBuffer === null) {
+                chunkBuffer = new Array(message.chunkCount);
+            }
+            chunkBuffer[message.chunkIndex] = message;
+            // have to check with Object.keys because the array is buffered and the length is not accurate
+            if (Object.keys(chunkBuffer).length !== message.chunkCount) {
+                return;
+            }
+            return buildResponseFromChunks(chunkBuffer);
+        }
+        return message;
+    }), filter(Boolean));
+}
+/** Given a complete set of chunks, build a single response. */
+function buildResponseFromChunks(chunks) {
+    const chunkPayloads = chunks.map((x) => x.payload).filter((x) => x !== undefined);
+    const payloadLength = chunkPayloads.reduce((acc, x) => acc + x.length, 0);
+    const mergedPayload = new Uint8Array(payloadLength);
+    for (let i = 0, offset = 0; i < chunkPayloads.length; i++) {
+        mergedPayload.set(chunkPayloads[i], offset);
+        offset += chunkPayloads[i].length;
+    }
+    const [header] = chunks.map((x) => x.header).filter((x) => x !== undefined);
+    if (header === undefined || Array.isArray(header)) {
+        throw new Error('No header found in chunks');
+    }
+    const [uid] = chunks.map((x) => x.uid).filter((x) => x !== undefined);
+    if (uid === undefined || Array.isArray(uid)) {
+        throw new Error('No uid found in chunks');
+    }
+    const createdAt = new Date(Number(header.created) * 1000);
+    const createdNs = (BigInt(header.created) * BigInt(1e9)).toString();
+    return {
+        uid,
+        return: {
+            header: {
+                createdNs,
+                createdAt,
+                meta: header.meta,
+            },
+            payload: mergedPayload,
+        },
+    };
+}

package/models/caller/IRocosCallerMessageChunk.d.ts

@@ -2,9 +2,14 @@ import { IRocosCallerMessageResponseAck } from './IRocosCallerMessageResponseAck
 import { IRocosCallerMessageResponseResult } from './IRocosCallerMessageResponseResult';
 import { IRocosCallerMessageResponseUid } from './IRocosCallerMessageResponseUid';
 export interface IRocosCallerMessageChunk {
+    uid?: IRocosCallerMessageResponseUid;
     chunkIndex: number;
     chunkCount: number;
-    uid?: IRocosCallerMessageResponseUid;
+    header?: {
+        created: string;
+        meta: Record<string, string>;
+    };
     ack?: IRocosCallerMessageResponseAck;
     result?: IRocosCallerMessageResponseResult;
+    payload?: Uint8Array;
 }

package/models/caller/index.d.ts

@@ -4,6 +4,7 @@ export * from './IRocosCallerMessageHeartbeat';
 export * from './IRocosCallerMessageResponse';
 export * from './IRocosCallerMessageResponseAck';
 export * from './IRocosCallerMessageResponseResult';
+export * from './IRocosCallerMessageResponseReturn';
 export * from './IRocosCallerMessageResponses';
 export * from './IRocosCallerMessageResponseUid';
 export * from './RocosCallerResultStatus';

package/models/caller/index.js

@@ -4,6 +4,7 @@ export * from './IRocosCallerMessageHeartbeat';
 export * from './IRocosCallerMessageResponse';
 export * from './IRocosCallerMessageResponseAck';
 export * from './IRocosCallerMessageResponseResult';
+export * from './IRocosCallerMessageResponseReturn';
 export * from './IRocosCallerMessageResponses';
 export * from './IRocosCallerMessageResponseUid';
 export * from './RocosCallerResultStatus';

package/models/params/ICallerParams.d.ts

@@ -14,3 +14,13 @@ export interface ICallerInvokeParams extends ICallerParams {
     payload: string;
     query?: Record<string, string[]>;
 }
+export interface ICallerCallParams {
+    projectId: string;
+    callsign: string;
+    source: string;
+    payload?: unknown;
+    options?: {
+        uid?: string;
+        query?: Record<string, string[]>;
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dronedeploy/rocos-js-sdk",
-  "version": "3.0.0-alpha.19",
+  "version": "3.0.0-alpha.20",
   "description": "Javascript SDK for rocos",
   "main": "index.js",
   "types": "index.d.ts",

package/services/CallerService.d.ts

@@ -1,10 +1,42 @@
-import { ICallerInvokeParams, ICallerParams, ICallerStream, IRocosCallerMessage, IRocosSDKConfig, IStreamConfig } from '../models';
+import { ICallerCallParams, ICallerInvokeParams, ICallerParams, ICallerStream, IRocosCallerMessage, IRocosCallerMessageResponseAck, IRocosCallerMessageResponseResult, IRocosCallerMessageResponseReturn, IRocosSDKConfig, IStreamConfig } from '../models';
 import { Observable } from 'rxjs';
 import { BaseStreamService } from './BaseStreamService';
 export declare class CallerService extends BaseStreamService<ICallerStream> {
     constructor(config: IRocosSDKConfig);
     invokeRequest(params: ICallerInvokeParams): Observable<IRocosCallerMessage>;
     cancelRequest(params: ICallerParams): Observable<IRocosCallerMessage>;
+    /** Call a service and return the response(s).
+     *
+     * It will complete once a result message is received with a `COMPLETE_SUCCESS` status,
+     * or throw an error if the status is not `COMPLETE_SUCCESS`.
+     *
+     * This is a high level method that wraps the lower level `invokeRequest` method.
+     *
+     * @see invokeRequest
+     * @see call
+     */
+    callRaw(params: ICallerCallParams): {
+        return$: Observable<IRocosCallerMessageResponseReturn>;
+        result$: Observable<IRocosCallerMessageResponseResult>;
+        ack$: Observable<IRocosCallerMessageResponseAck>;
+    };
+    /** Call a service and return the response(s) as UTF-8 encoded JSON.
+     *
+     * It will complete once a result message is received with a `COMPLETE_SUCCESS` status,
+     * or throw an error if the status is not `COMPLETE_SUCCESS`.
+     *
+     * This is a high level method that wraps the lower level `invokeRequest` method.
+     *
+     * Equivalent to calling `callRaw` and then parsing the return payload as UTF-8 encoded JSON.
+     *
+     * @see callRaw
+     * @see invokeRequest
+     */
+    call<T = unknown>(params: ICallerCallParams): {
+        return$: Observable<T>;
+        result$: Observable<IRocosCallerMessageResponseResult>;
+        ack$: Observable<IRocosCallerMessageResponseAck>;
+    };
     protected createStream(): Promise<ICallerStream>;
     protected getStream(config: IStreamConfig): ICallerStream;
 }

package/services/CallerService.js

@@ -1,8 +1,11 @@
-import { Subject } from 'rxjs';
+import { ResultStatus, RocosResponseLevel, } from '../models';
+import { Subject, map, mergeMap, take, takeUntil } from 'rxjs';
+import { filter, finalize } from 'rxjs/operators';
+import { getResponses, handleChunkedMessages } from '../helpers/callerMessageHelpers';
 import { BaseStreamService } from './BaseStreamService';
 import { CallerStream } from '../api/streams/caller/CallerStream';
 import { IDENTIFIER_NAME_CALLER } from '../constants/identifier';
-import { finalize } from 'rxjs/operators';
+import { v4 } from 'uuid';
 export class CallerService extends BaseStreamService {
     constructor(config) {
         super('CallerService', config);
@@ -37,6 +40,67 @@ export class CallerService extends BaseStreamService {
             subscription?.unsubscribe();
         }));
     }
+    /** Call a service and return the response(s).
+     *
+     * It will complete once a result message is received with a `COMPLETE_SUCCESS` status,
+     * or throw an error if the status is not `COMPLETE_SUCCESS`.
+     *
+     * This is a high level method that wraps the lower level `invokeRequest` method.
+     *
+     * @see invokeRequest
+     * @see call
+     */
+    callRaw(params) {
+        const [component, ...topicItems] = params.source.replace(/^\/+/, '').split('/');
+        const topic = topicItems.join('/');
+        const payloadString = JSON.stringify(params.payload ?? {});
+        const source$ = this.invokeRequest({
+            uid: params.options?.uid ?? v4(),
+            projectId: params.projectId,
+            callsign: params.callsign,
+            subSystem: '',
+            component,
+            topic,
+            responseLevelNumber: RocosResponseLevel.ALL,
+            payload: payloadString,
+            query: params.options?.query,
+        }).pipe(mergeMap(getResponses), handleChunkedMessages());
+        const result$ = source$.pipe(filter((x) => x.result !== undefined), map((x) => x.result), take(1));
+        const resultNotifier$ = result$.pipe(map((x) => {
+            if (x.status !== ResultStatus.COMPLETE_SUCCESS)
+                throw x;
+            return x;
+        }));
+        const return$ = source$.pipe(filter((x) => x.return !== undefined), map((x) => x.return), takeUntil(resultNotifier$));
+        const ack$ = source$.pipe(filter((x) => x.ack !== undefined), map((x) => x.ack), takeUntil(resultNotifier$));
+        return {
+            return$,
+            result$,
+            ack$,
+        };
+    }
+    /** Call a service and return the response(s) as UTF-8 encoded JSON.
+     *
+     * It will complete once a result message is received with a `COMPLETE_SUCCESS` status,
+     * or throw an error if the status is not `COMPLETE_SUCCESS`.
+     *
+     * This is a high level method that wraps the lower level `invokeRequest` method.
+     *
+     * Equivalent to calling `callRaw` and then parsing the return payload as UTF-8 encoded JSON.
+     *
+     * @see callRaw
+     * @see invokeRequest
+     */
+    call(params) {
+        const stream = this.callRaw(params);
+        return {
+            ...stream,
+            return$: stream.return$.pipe(map((x) => {
+                const decoded = new TextDecoder().decode(x.payload);
+                return JSON.parse(decoded);
+            })),
+        };
+    }
     async createStream() {
         return (await this.createStreamFromConfig(IDENTIFIER_NAME_CALLER, {
             url: this.config.url,

package/services/CallerService.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/services/CallerService.spec.js

@@ -0,0 +1,227 @@
+import { AckStatus, ResultStatus, Stage, UIDVersion, } from '../models';
+import { concatMap, delay, from, of } from 'rxjs';
+import { CallerService } from './CallerService';
+import { TestScheduler } from 'rxjs/testing';
+const makeCallerMessage = (responses) => ({
+    responses: {
+        responses: responses ?? [],
+    },
+});
+const makeCallerChunkedMessage = (responses) => {
+    return responses.map((response, index) => {
+        if ('return' in response) {
+            throw new Error('Cannot create chunked message with return');
+        }
+        const chunk = response;
+        chunk.chunkIndex = index;
+        chunk.chunkCount = responses.length;
+        chunk.header = {
+            created: '0',
+            meta: {},
+        };
+        return {
+            chunks: {
+                chunks: [chunk],
+            },
+        };
+    });
+};
+const uid = {
+    hash: 'hash',
+    version: UIDVersion.HEADER_HASH_RAND,
+};
+const ack = (id) => ({
+    uid,
+    ack: {
+        status: AckStatus.PROGRESS,
+        message: id,
+        stage: Stage.AGENT,
+    },
+});
+const ret = (id) => {
+    const encoder = new TextEncoder();
+    const payload = encoder.encode(JSON.stringify({ id }));
+    return {
+        uid,
+        return: {
+            payload,
+        },
+    };
+};
+const chunkRet = (payload) => {
+    const array = new TextEncoder().encode(payload);
+    return {
+        uid,
+        payload: array,
+        chunkIndex: 0,
+        chunkCount: 1,
+        header: {
+            created: '0',
+            meta: {},
+        },
+    };
+};
+const res = (ok) => ({
+    uid,
+    result: {
+        status: ok ? ResultStatus.COMPLETE_SUCCESS : ResultStatus.FATAL,
+        message: ok ? 'everything is fine' : 'nothing is fine',
+    },
+});
+let testScheduler;
+let service;
+describe('CallerService', () => {
+    beforeEach(() => {
+        service = new CallerService({
+            url: 'http://localhost:8080',
+            token: 'token',
+        });
+        testScheduler = new TestScheduler((actual, expected) => {
+            expect(actual).toEqual(expected);
+        });
+    });
+    describe('callRaw', () => {
+        it('should handle a successful call', () => {
+            // Arrange
+            jest.spyOn(service, 'invokeRequest').mockImplementation(() => {
+                return from([
+                    makeCallerMessage([ack('a')]),
+                    makeCallerMessage([ack('b')]),
+                    makeCallerMessage([ack('c'), ret(1)]),
+                    makeCallerMessage([ret(2)]),
+                    makeCallerMessage([ret(3), ret(4)]),
+                    makeCallerMessage([ack('d')]),
+                    makeCallerMessage([ack('e')]),
+                    makeCallerMessage([ack('f')]),
+                    makeCallerMessage([ack('g'), res(true)]),
+                    makeCallerMessage([ack('h')]),
+                ]).pipe(concatMap((item) => of(item).pipe(delay(1))));
+            });
+            testScheduler.run(({ expectObservable }) => {
+                // Act
+                const call = service.call({
+                    callsign: 'callsign',
+                    projectId: 'project',
+                    source: '/test',
+                });
+                // Assert
+                const expectedAckMarbles = '-abc--def|';
+                const expectedRetMarbles = '---ab(cd)|';
+                const expectedResMarbles = '---------(a|)';
+                const expectedAckValues = {
+                    a: { stage: Stage.AGENT, status: AckStatus.PROGRESS, message: 'a' },
+                    b: { stage: Stage.AGENT, status: AckStatus.PROGRESS, message: 'b' },
+                    c: { stage: Stage.AGENT, status: AckStatus.PROGRESS, message: 'c' },
+                    d: { stage: Stage.AGENT, status: AckStatus.PROGRESS, message: 'd' },
+                    e: { stage: Stage.AGENT, status: AckStatus.PROGRESS, message: 'e' },
+                    f: { stage: Stage.AGENT, status: AckStatus.PROGRESS, message: 'f' },
+                };
+                const expectedReturnValues = {
+                    a: { id: 1 },
+                    b: { id: 2 },
+                    c: { id: 3 },
+                    d: { id: 4 },
+                };
+                const expectedResultValues = {
+                    a: { status: ResultStatus.COMPLETE_SUCCESS, message: 'everything is fine' },
+                };
+                expectObservable(call.ack$).toBe(expectedAckMarbles, expectedAckValues);
+                expectObservable(call.return$).toBe(expectedRetMarbles, expectedReturnValues);
+                expectObservable(call.result$).toBe(expectedResMarbles, expectedResultValues);
+            });
+        });
+        it('should handle a failed call', () => {
+            // Arrange
+            jest.spyOn(service, 'invokeRequest').mockImplementation(() => {
+                return from([
+                    makeCallerMessage([ack('a')]),
+                    makeCallerMessage([ack('b')]),
+                    makeCallerMessage([ack('c'), ret(1)]),
+                    makeCallerMessage([ret(2)]),
+                    makeCallerMessage([ret(3), ret(4)]),
+                    makeCallerMessage([ack('d')]),
+                    makeCallerMessage([ack('e')]),
+                    makeCallerMessage([ack('f')]),
+                    makeCallerMessage([ack('g'), res(false)]),
+                    makeCallerMessage([ack('h')]),
+                ]).pipe(concatMap((item) => of(item).pipe(delay(1))));
+            });
+            testScheduler.run(({ expectObservable }) => {
+                // Act
+                const call = service.call({
+                    callsign: 'callsign',
+                    projectId: 'project',
+                    source: '/test',
+                });
+                // Assert
+                const expectedAckMarbles = '-abc--def#';
+                const expectedRetMarbles = '---ab(cd)#';
+                const expectedResMarbles = '---------(a|)';
+                const expectedAckValues = {
+                    a: { stage: Stage.AGENT, status: AckStatus.PROGRESS, message: 'a' },
+                    b: { stage: Stage.AGENT, status: AckStatus.PROGRESS, message: 'b' },
+                    c: { stage: Stage.AGENT, status: AckStatus.PROGRESS, message: 'c' },
+                    d: { stage: Stage.AGENT, status: AckStatus.PROGRESS, message: 'd' },
+                    e: { stage: Stage.AGENT, status: AckStatus.PROGRESS, message: 'e' },
+                    f: { stage: Stage.AGENT, status: AckStatus.PROGRESS, message: 'f' },
+                };
+                const expectedReturnValues = {
+                    a: { id: 1 },
+                    b: { id: 2 },
+                    c: { id: 3 },
+                    d: { id: 4 },
+                };
+                const expectedResultValues = {
+                    a: { status: ResultStatus.FATAL, message: 'nothing is fine' },
+                };
+                expectObservable(call.ack$).toBe(expectedAckMarbles, expectedAckValues, res(false).result);
+                expectObservable(call.return$).toBe(expectedRetMarbles, expectedReturnValues, res(false).result);
+                expectObservable(call.result$).toBe(expectedResMarbles, expectedResultValues);
+            });
+        });
+        it('should handle a successful chunked call', () => {
+            // Arrange
+            jest.spyOn(service, 'invokeRequest').mockImplementation(() => {
+                return from([
+                    ...makeCallerChunkedMessage([
+                        chunkRet('[{"'),
+                        chunkRet('id":1},'),
+                        ack('a'),
+                        chunkRet('{"id":2}'),
+                        ack('b'),
+                        chunkRet(']'),
+                    ]),
+                    makeCallerMessage([ack('c'), ret(3)]),
+                    makeCallerMessage([res(true)]),
+                ]).pipe(concatMap((item) => of(item).pipe(delay(1))));
+            });
+            testScheduler.run(({ expectObservable }) => {
+                // Act
+                const call = service.call({
+                    callsign: 'callsign',
+                    projectId: 'project',
+                    source: '/test',
+                });
+                // Assert
+                const expectedAckMarbles = '---a-b-c|';
+                const expectedRetMarbles = '------ab|';
+                const expectedResMarbles = '--------(a|)';
+                const expectedAckValues = {
+                    a: { stage: Stage.AGENT, status: AckStatus.PROGRESS, message: 'a' },
+                    b: { stage: Stage.AGENT, status: AckStatus.PROGRESS, message: 'b' },
+                    c: { stage: Stage.AGENT, status: AckStatus.PROGRESS, message: 'c' },
+                };
+                const expectedReturnValues = {
+                    a: [{ id: 1 }, { id: 2 }],
+                    b: { id: 3 },
+                };
+                const expectedResultValues = {
+                    a: { status: ResultStatus.COMPLETE_SUCCESS, message: 'everything is fine' },
+                };
+                expectObservable(call.ack$).toBe(expectedAckMarbles, expectedAckValues);
+                expectObservable(call.return$).toBe(expectedRetMarbles, expectedReturnValues);
+                expectObservable(call.result$).toBe(expectedResMarbles, expectedResultValues);
+            });
+        });
+    });
+});