gingersnap 0.22.0

package/networking/NetworkService.cjs

@@ -0,0 +1,394 @@
+'use strict';
+
+var _tslib = require('../_virtual/_tslib.cjs');
+var model = require('../data/model/model.cjs');
+var R = require('ramda');
+var CallExecutionError = require('../errors/CallExecutionError.cjs');
+require('../data/model/types.cjs');
+var credentials = require('../data/model/credentials.cjs');
+var types = require('./types.cjs');
+var stream_call = require('../stream/call.cjs');
+var options = require('./decorators/options.cjs');
+var requests = require('./decorators/requests.cjs');
+var http = require('./http.cjs');
+require('uuid');
+var request = require('./request.cjs');
+var future = require('../future/future.cjs');
+var stream = require('../stream.cjs');
+var hash = require('object-hash');
+var manager = require('../data/store/manager.cjs');
+var stream_collector = require('../stream/collector.cjs');
+
+function _interopNamespaceDefault(e) {
+  var n = Object.create(null);
+  if (e) {
+    Object.keys(e).forEach(function (k) {
+      if (k !== 'default') {
+        var d = Object.getOwnPropertyDescriptor(e, k);
+        Object.defineProperty(n, k, d.get ? d : {
+          enumerable: true,
+          get: function () { return e[k]; }
+        });
+      }
+    });
+  }
+  n.default = e;
+  return Object.freeze(n);
+}
+
+var R__namespace = /*#__PURE__*/_interopNamespaceDefault(R);
+
+/**
+ * A Snap Service for managing network requests
+ */
+class NetworkService {
+    constructor({ baseUrl, retryLimit, cacheManager } = {}) {
+        var _a, _b, _c;
+        this.retryLimit = retryLimit;
+        this.__internal__ = (_a = this.__internal__) !== null && _a !== void 0 ? _a : { classConfig: {}, methodConfig: {} };
+        this.baseUrl = (_c = (_b = this.__internal__.classConfig.baseUrl) !== null && _b !== void 0 ? _b : baseUrl) !== null && _c !== void 0 ? _c : "";
+        this.cacheManager = cacheManager !== null && cacheManager !== void 0 ? cacheManager : new manager.CacheManager();
+    }
+    /**
+     * Converts the given value to a JSON object
+     * @param value Any data
+     * @private
+     */
+    convertToJSON(value) {
+        if (value instanceof model.Model) {
+            return value.json();
+        }
+        else if (value instanceof Array || Array.isArray(value)) {
+            return `[${value.map((v) => this.convertToJSON(v))}]`;
+        }
+        return typeof value === "string" ? value : JSON.stringify(value);
+    }
+    /**
+     * Internal method called to wrap all network request methods with actual networking functionalities
+     * @private
+     */
+    __setup__() {
+        const hostname = this.baseUrl;
+        const self = this;
+        R__namespace.forEach(([key, value]) => {
+            var _a, _b, _c, _d, _e, _f;
+            let headers = (_a = value.headers) !== null && _a !== void 0 ? _a : {};
+            const apiPath = (_b = value.apiPath) !== null && _b !== void 0 ? _b : "";
+            const oldMethod = self[key];
+            const auth = { global: (_f = (_d = (_c = value.authRefresher) === null || _c === void 0 ? void 0 : _c.global) !== null && _d !== void 0 ? _d : (_e = value.authenticator) === null || _e === void 0 ? void 0 : _e.global) !== null && _f !== void 0 ? _f : false };
+            if (value.requestType === undefined) {
+                this.__setup_authentication__(value, key, self[key], auth);
+                return;
+            }
+            const requestType = value.requestType;
+            const cacheInfo = value.cache;
+            let cache;
+            if (cacheInfo) {
+                cache = this.cacheManager.createCache(this.baseUrl, cacheInfo.persist, (resp) => _tslib.__awaiter(this, void 0, void 0, function* () {
+                    return JSON.stringify({
+                        headers: Object.fromEntries(resp.headers),
+                        status: resp.status,
+                        statusText: resp.statusText,
+                        body: yield stream.Stream.of(resp.body).collect(stream_collector.Collectors.asList()),
+                    });
+                }), (v) => {
+                    const { headers, status, statusText, body } = JSON.parse(v);
+                    return new Response(stream.Stream.of(body).readableStream, { status, statusText, headers });
+                }, undefined, cacheInfo.duration);
+            }
+            self[key] = (...args) => {
+                var _a;
+                let url = new URL((hostname.endsWith("/") ? hostname.substring(0, hostname.length) : hostname) +
+                    (apiPath.startsWith("/") ? apiPath : "/" + apiPath));
+                return new stream_call.Call((signal) => _tslib.__awaiter(this, void 0, void 0, function* () {
+                    headers = Object.assign(Object.assign({}, headers), this.__get_auth_headers__(auth));
+                    const result = this.__constructor_call_args__(url, headers, value, args);
+                    headers = result.headers;
+                    url = result.url;
+                    const body = result.body;
+                    if (cache && cacheInfo.method === requests.CachingMethod.HIT_FIRST) {
+                        let key = `${url.toString()}-${requestType.toString()}-${hash.sha1(headers)}`;
+                        if (body) {
+                            key += hash(body);
+                        }
+                        const result = yield cache.get(key).registerSignal(signal);
+                        if (result) {
+                            return result.clone();
+                        }
+                    }
+                    const lookup = (retries = 0) => request.request(url, { headers, method: requestType.toString(), body }).thenApply(({ value: resp }) => _tslib.__awaiter(this, void 0, void 0, function* () {
+                        let credentials;
+                        if (resp.status === http.HTTPStatus.UNAUTHORIZED &&
+                            !value.noAuth &&
+                            self[key] !== auth.authenticator &&
+                            self[key] !== auth.authRefresher &&
+                            (credentials = yield this.__get_credentials__(auth))) {
+                            return request.request(url, {
+                                headers: Object.assign(Object.assign({}, headers), credentials.buildAuthHeaders()),
+                                method: requestType.toString(),
+                                body,
+                            });
+                        }
+                        else if ((resp.status === http.HTTPStatus.GATEWAY_TIMEOUT || resp.status === http.HTTPStatus.SERVICE_UNAVAILABLE) &&
+                            self.retryLimit &&
+                            retries < self.retryLimit) {
+                            return future.Future.sleep({ milliseconds: options.THROTTLE_DEFAULT_MS }).thenApply(() => lookup(retries + 1));
+                        }
+                        if (cache) {
+                            let key = `${url.toString()}-${requestType.toString()}-${hash.sha1(headers)}`;
+                            if (resp.ok) {
+                                if (body) {
+                                    key += hash(body);
+                                }
+                                cache.set(key, resp.clone());
+                            }
+                            else if (cache && !resp.ok && cacheInfo.method === requests.CachingMethod.FALLBACK_ON_MISSING) {
+                                return cache.get(key);
+                            }
+                        }
+                        return resp;
+                    }));
+                    return lookup().registerSignal(signal);
+                }), oldMethod, value.responseClass, value.throttle, (_a = value.responseType) !== null && _a !== void 0 ? _a : types.ResponseType.NONE, value.responseArray);
+            };
+            this.__setup_authentication__(value, key, self[key], auth);
+        }, R__namespace.toPairs(this.__internal__.methodConfig));
+    }
+    __constructor_call_args__(url, headers, value, args) {
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q;
+        let body;
+        if (value.parameters) {
+            const paramHeaders = (_a = value.parameters.headers) !== null && _a !== void 0 ? _a : {};
+            const paramQueries = (_b = value.parameters.queries) !== null && _b !== void 0 ? _b : {};
+            const paramHeaderPairs = R__namespace.concat(R__namespace.toPairs(paramHeaders), R__namespace.map((k) => [k, paramHeaders[k]], Object.getOwnPropertySymbols(paramHeaders)));
+            const paramQueryPairs = R__namespace.concat(R__namespace.toPairs(paramQueries), R__namespace.map((k) => [k, paramQueries[k]], Object.getOwnPropertySymbols(paramQueries)));
+            R__namespace.forEach(([key, index]) => {
+                const arg = args[index];
+                if (arg === undefined) {
+                    throw new CallExecutionError.CallExecutionError(`header parameter is missing at index ${index}`);
+                }
+                if (typeof key === "symbol" && typeof arg === "object") {
+                    headers = Object.assign(Object.assign({}, headers), arg);
+                }
+                else {
+                    headers[key] = headers[key] ? `${R__namespace.prop(key, headers)};${String(args[index])}` : String(args[index]);
+                }
+            }, paramHeaderPairs);
+            R__namespace.forEach(([key, index]) => {
+                if (args[index] === undefined) {
+                    throw new CallExecutionError.CallExecutionError(`path parameter is missing at index ${index}`);
+                }
+                url.pathname = url.pathname.replace(encodeURI(`{${key}}`), encodeURI(args[index]));
+            }, R__namespace.toPairs((_c = value.parameters.pathVariables) !== null && _c !== void 0 ? _c : {}));
+            R__namespace.forEach(([key, index]) => {
+                const arg = args[index];
+                if (arg === undefined) {
+                    throw new CallExecutionError.CallExecutionError(`query parameter is missing at index ${index}`);
+                }
+                if (typeof key === "symbol" && typeof arg === "object") {
+                    R__namespace.forEach(([k, v]) => {
+                        url.searchParams.set(k, v);
+                    }, R__namespace.toPairs(arg));
+                }
+                else {
+                    url.searchParams.set(key, arg);
+                }
+            }, paramQueryPairs);
+            if ((_d = value.parameters.body) === null || _d === void 0 ? void 0 : _d.type) {
+                switch (value.parameters.body.type) {
+                    case types.BodyType.STRING: {
+                        const index = (_e = value.parameters.body.parameterIndex) !== null && _e !== void 0 ? _e : -1;
+                        if (args[index] === undefined) {
+                            throw new CallExecutionError.CallExecutionError(`body parameter is missing at index ${index}`);
+                        }
+                        body = this.convertToJSON(args[index]);
+                        break;
+                    }
+                    case types.BodyType.JSON: {
+                        headers["Content-Type"] = (_f = headers["Content-Type"]) !== null && _f !== void 0 ? _f : "application/json";
+                        const index = (_g = value.parameters.body.parameterIndex) !== null && _g !== void 0 ? _g : -1;
+                        let data = {};
+                        if (args[index] === undefined) {
+                            const fields = value.parameters.body.fields;
+                            if (!fields) {
+                                throw new CallExecutionError.CallExecutionError(`body parameter is missing at index ${index}`);
+                            }
+                            R__namespace.forEach(([key, index]) => {
+                                const arg = args[index];
+                                if (arg === undefined) {
+                                    throw new CallExecutionError.CallExecutionError(`form field is missing at index ${index}`);
+                                }
+                                data[key] = arg;
+                            }, R__namespace.toPairs((_h = value.parameters.body.fields) !== null && _h !== void 0 ? _h : {}));
+                            R__namespace.forEach(([key, index]) => {
+                                const arg = args[index];
+                                if (arg !== undefined && arg !== null) {
+                                    data[key] = arg;
+                                }
+                            }, R__namespace.toPairs((_j = value.parameters.body.optionalFields) !== null && _j !== void 0 ? _j : {}));
+                        }
+                        else {
+                            data = args[index];
+                        }
+                        body = this.convertToJSON(data);
+                        break;
+                    }
+                    case types.BodyType.XML: {
+                        const index = value.parameters.body.parameterIndex;
+                        const arg = args[index];
+                        if (arg === undefined) {
+                            throw new CallExecutionError.CallExecutionError(`body parameter is missing at index ${index}`);
+                        }
+                        body = arg instanceof model.Model ? arg.xml() : new XMLSerializer().serializeToString(arg);
+                        break;
+                    }
+                    case types.BodyType.FORMURLENCODED: {
+                        headers["Content-Type"] = (_k = headers["Content-Type"]) !== null && _k !== void 0 ? _k : "application/x-www-form-urlencoded";
+                        const formData = new URLSearchParams();
+                        R__namespace.forEach(([key, index]) => {
+                            const arg = args[index];
+                            if (arg === undefined) {
+                                throw new CallExecutionError.CallExecutionError(`form field is missing at index ${index}`);
+                            }
+                            formData.set(key, arg);
+                        }, R__namespace.toPairs((_l = value.parameters.body.fields) !== null && _l !== void 0 ? _l : {}));
+                        R__namespace.forEach(([key, index]) => {
+                            const arg = args[index];
+                            if (arg !== undefined && arg !== null) {
+                                formData.set(key, arg);
+                            }
+                        }, R__namespace.toPairs((_m = value.parameters.body.optionalFields) !== null && _m !== void 0 ? _m : {}));
+                        body = formData;
+                        break;
+                    }
+                    case types.BodyType.MULTIPART: {
+                        headers["Content-Type"] = (_o = headers["Content-Type"]) !== null && _o !== void 0 ? _o : "multipart/form-data";
+                        const formData = new FormData();
+                        R__namespace.forEach(([key, index]) => {
+                            const arg = args[index];
+                            if (arg === undefined) {
+                                throw new CallExecutionError.CallExecutionError(`form part is missing at index ${index}`);
+                            }
+                            formData.append(key, arg);
+                        }, R__namespace.toPairs((_p = value.parameters.body.parts) !== null && _p !== void 0 ? _p : {}));
+                        body = formData;
+                        break;
+                    }
+                    default:
+                        throw new CallExecutionError.CallExecutionError(`Unsupported body type: ${(_q = value.parameters.body) === null || _q === void 0 ? void 0 : _q.type}`);
+                }
+            }
+        }
+        return { body, headers, url };
+    }
+    /**
+     * Retrieves the authentication headers
+     * @param auth AuthInstance
+     * @private
+     */
+    __get_auth_headers__(auth) {
+        const classRef = this.constructor;
+        if (!auth.global && classRef.credentials)
+            return classRef.credentials.buildAuthHeaders();
+        else if (auth.global && NetworkService.credentials)
+            return NetworkService.credentials.buildAuthHeaders();
+        return {};
+    }
+    /**
+     * Retrieves the auth credentials, and if no valid on exists, attempt to fetch it via the authenticator/authRefresher
+     * @param auth AuthInstance
+     * @private
+     */
+    __get_credentials__(auth) {
+        return _tslib.__awaiter(this, void 0, void 0, function* () {
+            let result;
+            let credentials;
+            const classRef = this.constructor;
+            if (auth.global && NetworkService.credentials && auth.authRefresher) {
+                result = auth.authRefresher(NetworkService.credentials);
+            }
+            else if (!auth.global && classRef.credentials && auth.authRefresher) {
+                result = auth.authRefresher(classRef.credentials);
+            }
+            else if (auth.authenticator) {
+                result = auth.authenticator();
+            }
+            else {
+                return;
+            }
+            if (result instanceof stream_call.Call) {
+                credentials = yield result.execute();
+            }
+            else if (result instanceof Promise) {
+                credentials = yield result;
+            }
+            else {
+                credentials = result;
+            }
+            if (auth.global)
+                NetworkService.credentials = credentials;
+            else
+                classRef.credentials = credentials;
+            return credentials;
+        });
+    }
+    /**
+     * Configures authentication if none exist by assigning the authenticator to the correct scope
+     * (Global -> Service, Local -> this)
+     * @param config MethodConfiguration
+     * @param methodName name of the method that should hold the authenticator
+     * @param functor authenticator
+     * @param auth AuthInstance
+     * @private
+     */
+    __setup_authentication__(config, methodName, functor, auth) {
+        const classRef = this.constructor;
+        if (config.authenticator) {
+            if (config.authenticator.global && !NetworkService.authenticator) {
+                NetworkService.authenticator = functor;
+            }
+            else if (!config.authenticator.global && !classRef.authenticator) {
+                classRef.authenticator = functor;
+            }
+            const parentRef = config.authenticator.global ? NetworkService : classRef;
+            const oldMethod = this[methodName];
+            this[methodName] = (...args) => {
+                const result = oldMethod(...args);
+                if (result instanceof Promise) {
+                    return result.then((v) => {
+                        if (v instanceof credentials.Credentials) {
+                            parentRef.credentials = v;
+                        }
+                        return v;
+                    });
+                }
+                else if (result instanceof credentials.Credentials) {
+                    parentRef.credentials = result;
+                }
+                return result;
+            };
+        }
+        if (config.authRefresher) {
+            if (config.authRefresher.global && !NetworkService.authRefresher) {
+                NetworkService.authRefresher = functor;
+            }
+            else if (!config.authRefresher.global && !classRef.authRefresher) {
+                classRef.authRefresher = functor;
+            }
+        }
+        if (NetworkService.authenticator) {
+            auth.authenticator = NetworkService.authenticator;
+        }
+        else if (classRef.authenticator) {
+            auth.authenticator = classRef.authenticator;
+        }
+        if (NetworkService.authRefresher) {
+            auth.authRefresher = NetworkService.authRefresher;
+        }
+        else if (classRef.authRefresher) {
+            auth.authRefresher = classRef.authRefresher;
+        }
+    }
+}
+
+exports.NetworkService = NetworkService;

package/networking/NetworkService.d.ts

@@ -0,0 +1,97 @@
+import { GingerSnapProps } from "./index";
+import { TimeableObject } from "../data-structures/object";
+import { CacheManager } from "../data/store/manager";
+/**
+ * A Snap Service for managing network requests
+ */
+export declare class NetworkService {
+    /**
+     * BaseUrl used by this snap service
+     * @private
+     */
+    protected readonly baseUrl: string;
+    /**
+     * Request retry limit used by this snap service
+     * @private
+     */
+    private readonly retryLimit?;
+    protected readonly cacheManager: CacheManager;
+    /**
+     * Internal properties used to construct this snap service
+     * @private
+     */
+    private readonly __internal__;
+    /**
+     * Function that handles authentication refresh
+     * @private
+     */
+    private static authRefresher?;
+    /**
+     * Function that handles authentication
+     * @private
+     */
+    private static authenticator?;
+    /**
+     * Credentials used for authenticated network requests sent by this snap service
+     * @private
+     */
+    private static credentials?;
+    /**
+     * Context representing ResponseData created after the network request is complete.
+     * Value varies per network request method, and is scoped to the calling method
+     * @example
+     * ```ts
+     * class Snap extends Service {
+     *   @GET("/data")
+     *   @JSONResponse(Data)
+     *   public getData(): Call<Data> {
+     *     // do post processing with the Data model
+     *     console.log('Data model is returned to this.context variable');
+     *     console.log(this.context);
+     *   }
+     * }
+     * ```
+     * @protected
+     */
+    protected context: any;
+    /**
+     * Cache containing the results from cached network lookups
+     * @protected
+     */
+    protected lookupCache: TimeableObject<string, any>;
+    constructor({ baseUrl, retryLimit, cacheManager }?: GingerSnapProps);
+    /**
+     * Converts the given value to a JSON object
+     * @param value Any data
+     * @private
+     */
+    private convertToJSON;
+    /**
+     * Internal method called to wrap all network request methods with actual networking functionalities
+     * @private
+     */
+    protected __setup__(): void;
+    private __constructor_call_args__;
+    /**
+     * Retrieves the authentication headers
+     * @param auth AuthInstance
+     * @private
+     */
+    private __get_auth_headers__;
+    /**
+     * Retrieves the auth credentials, and if no valid on exists, attempt to fetch it via the authenticator/authRefresher
+     * @param auth AuthInstance
+     * @private
+     */
+    private __get_credentials__;
+    /**
+     * Configures authentication if none exist by assigning the authenticator to the correct scope
+     * (Global -> Service, Local -> this)
+     * @param config MethodConfiguration
+     * @param methodName name of the method that should hold the authenticator
+     * @param functor authenticator
+     * @param auth AuthInstance
+     * @private
+     */
+    private __setup_authentication__;
+}