eteres 0.0.1-security → 6.7.1

package/lib.commonjs/utils/fetch.d.ts

@@ -0,0 +1,334 @@
+/**
+ *  An environments implementation of ``getUrl`` must return this type.
+ */
+export type GetUrlResponse = {
+    statusCode: number;
+    statusMessage: string;
+    headers: Record<string, string>;
+    body: null | Uint8Array;
+};
+/**
+ *  This can be used to control how throttling is handled in
+ *  [[FetchRequest-setThrottleParams]].
+ */
+export type FetchThrottleParams = {
+    maxAttempts?: number;
+    slotInterval?: number;
+};
+/**
+ *  Called before any network request, allowing updated headers (e.g. Bearer tokens), etc.
+ */
+export type FetchPreflightFunc = (req: FetchRequest) => Promise<FetchRequest>;
+/**
+ *  Called on the response, allowing client-based throttling logic or post-processing.
+ */
+export type FetchProcessFunc = (req: FetchRequest, resp: FetchResponse) => Promise<FetchResponse>;
+/**
+ *  Called prior to each retry; return true to retry, false to abort.
+ */
+export type FetchRetryFunc = (req: FetchRequest, resp: FetchResponse, attempt: number) => Promise<boolean>;
+/**
+ *  Called on Gateway URLs.
+ */
+export type FetchGatewayFunc = (url: string, signal?: FetchCancelSignal) => Promise<FetchRequest | FetchResponse>;
+/**
+ *  Used to perform a fetch; use this to override the underlying network
+ *  fetch layer. In NodeJS, the default uses the "http" and "https" libraries
+ *  and in the browser ``fetch`` is used. If you wish to use Axios, this is
+ *  how you would register it.
+ */
+export type FetchGetUrlFunc = (req: FetchRequest, signal?: FetchCancelSignal) => Promise<GetUrlResponse>;
+/**
+ *  @_ignore
+ */
+export declare class FetchCancelSignal {
+    #private;
+    constructor(request: FetchRequest);
+    addListener(listener: () => void): void;
+    get cancelled(): boolean;
+    checkSignal(): void;
+}
+/**
+ *  Represents a request for a resource using a URI.
+ *
+ *  By default, the supported schemes are ``HTTP``, ``HTTPS``, ``data:``,
+ *  and ``IPFS:``.
+ *
+ *  Additional schemes can be added globally using [[registerGateway]].
+ *
+ *  @example:
+ *    req = new FetchRequest("https://www.ricmoo.com")
+ *    resp = await req.send()
+ *    resp.body.length
+ *    //_result:
+ */
+export declare class FetchRequest implements Iterable<[key: string, value: string]> {
+    #private;
+    /**
+     *  The fetch URI to requrest.
+     */
+    get url(): string;
+    set url(url: string);
+    /**
+     *  The fetch body, if any, to send as the request body. //(default: null)//
+     *
+     *  When setting a body, the intrinsic ``Content-Type`` is automatically
+     *  set and will be used if **not overridden** by setting a custom
+     *  header.
+     *
+     *  If %%body%% is null, the body is cleared (along with the
+     *  intrinsic ``Content-Type``) and the .
+     *
+     *  If %%body%% is a string, the intrincis ``Content-Type`` is set to
+     *  ``text/plain``.
+     *
+     *  If %%body%% is a Uint8Array, the intrincis ``Content-Type`` is set to
+     *  ``application/octet-stream``.
+     *
+     *  If %%body%% is any other object, the intrincis ``Content-Type`` is
+     *  set to ``application/json``.
+     */
+    get body(): null | Uint8Array;
+    set body(body: null | string | Readonly<object> | Readonly<Uint8Array>);
+    /**
+     *  Returns true if the request has a body.
+     */
+    hasBody(): this is (FetchRequest & {
+        body: Uint8Array;
+    });
+    /**
+     *  The HTTP method to use when requesting the URI. If no method
+     *  has been explicitly set, then ``GET`` is used if the body is
+     *  null and ``POST`` otherwise.
+     */
+    get method(): string;
+    set method(method: null | string);
+    /**
+     *  The headers that will be used when requesting the URI. All
+     *  keys are lower-case.
+     *
+     *  This object is a copy, so any chnages will **NOT** be reflected
+     *  in the ``FetchRequest``.
+     *
+     *  To set a header entry, use the ``setHeader`` method.
+     */
+    get headers(): Record<string, string>;
+    /**
+     *  Get the header for %%key%%, ignoring case.
+     */
+    getHeader(key: string): string;
+    /**
+     *  Set the header for %%key%% to %%value%%. All values are coerced
+     *  to a string.
+     */
+    setHeader(key: string, value: string | number): void;
+    /**
+     *  Clear all headers, resetting all intrinsic headers.
+     */
+    clearHeaders(): void;
+    [Symbol.iterator](): Iterator<[key: string, value: string]>;
+    /**
+     *  The value that will be sent for the ``Authorization`` header.
+     *
+     *  To set the credentials, use the ``setCredentials`` method.
+     */
+    get credentials(): null | string;
+    /**
+     *  Sets an ``Authorization`` for %%username%% with %%password%%.
+     */
+    setCredentials(username: string, password: string): void;
+    /**
+     *  Enable and request gzip-encoded responses. The response will
+     *  automatically be decompressed. //(default: true)//
+     */
+    get allowGzip(): boolean;
+    set allowGzip(value: boolean);
+    /**
+     *  Allow ``Authentication`` credentials to be sent over insecure
+     *  channels. //(default: false)//
+     */
+    get allowInsecureAuthentication(): boolean;
+    set allowInsecureAuthentication(value: boolean);
+    /**
+     *  The timeout (in milliseconds) to wait for a complere response.
+     *  //(default: 5 minutes)//
+     */
+    get timeout(): number;
+    set timeout(timeout: number);
+    /**
+     *  This function is called prior to each request, for example
+     *  during a redirection or retry in case of server throttling.
+     *
+     *  This offers an opportunity to populate headers or update
+     *  content before sending a request.
+     */
+    get preflightFunc(): null | FetchPreflightFunc;
+    set preflightFunc(preflight: null | FetchPreflightFunc);
+    /**
+     *  This function is called after each response, offering an
+     *  opportunity to provide client-level throttling or updating
+     *  response data.
+     *
+     *  Any error thrown in this causes the ``send()`` to throw.
+     *
+     *  To schedule a retry attempt (assuming the maximum retry limit
+     *  has not been reached), use [[response.throwThrottleError]].
+     */
+    get processFunc(): null | FetchProcessFunc;
+    set processFunc(process: null | FetchProcessFunc);
+    /**
+     *  This function is called on each retry attempt.
+     */
+    get retryFunc(): null | FetchRetryFunc;
+    set retryFunc(retry: null | FetchRetryFunc);
+    /**
+     *  Create a new FetchRequest instance with default values.
+     *
+     *  Once created, each property may be set before issuing a
+     *  ``.send()`` to make the request.
+     */
+    constructor(url: string);
+    toString(): string;
+    /**
+     *  Update the throttle parameters used to determine maximum
+     *  attempts and exponential-backoff properties.
+     */
+    setThrottleParams(params: FetchThrottleParams): void;
+    /**
+     *  Resolves to the response by sending the request.
+     */
+    send(): Promise<FetchResponse>;
+    /**
+     *  Cancels the inflight response, causing a ``CANCELLED``
+     *  error to be rejected from the [[send]].
+     */
+    cancel(): void;
+    /**
+     *  Returns a new [[FetchRequest]] that represents the redirection
+     *  to %%location%%.
+     */
+    redirect(location: string): FetchRequest;
+    /**
+     *  Create a new copy of this request.
+     */
+    clone(): FetchRequest;
+    /**
+     *  Locks all static configuration for gateways and FetchGetUrlFunc
+     *  registration.
+     */
+    static lockConfig(): void;
+    /**
+     *  Get the current Gateway function for %%scheme%%.
+     */
+    static getGateway(scheme: string): null | FetchGatewayFunc;
+    /**
+     *  Use the %%func%% when fetching URIs using %%scheme%%.
+     *
+     *  This method affects all requests globally.
+     *
+     *  If [[lockConfig]] has been called, no change is made and this
+     *  throws.
+     */
+    static registerGateway(scheme: string, func: FetchGatewayFunc): void;
+    /**
+     *  Use %%getUrl%% when fetching URIs over HTTP and HTTPS requests.
+     *
+     *  This method affects all requests globally.
+     *
+     *  If [[lockConfig]] has been called, no change is made and this
+     *  throws.
+     */
+    static registerGetUrl(getUrl: FetchGetUrlFunc): void;
+    /**
+     *  Creates a function that can "fetch" data URIs.
+     *
+     *  Note that this is automatically done internally to support
+     *  data URIs, so it is not necessary to register it.
+     *
+     *  This is not generally something that is needed, but may
+     *  be useful in a wrapper to perfom custom data URI functionality.
+     */
+    static createDataGateway(): FetchGatewayFunc;
+    /**
+     *  Creates a function that will fetch IPFS (unvalidated) from
+     *  a custom gateway baseUrl.
+     *
+     *  The default IPFS gateway used internally is
+     *  ``"https:/\/gateway.ipfs.io/ipfs/"``.
+     */
+    static createIpfsGatewayFunc(baseUrl: string): FetchGatewayFunc;
+}
+/**
+ *  The response for a FetchREquest.
+ */
+export declare class FetchResponse implements Iterable<[key: string, value: string]> {
+    #private;
+    toString(): string;
+    /**
+     *  The response status code.
+     */
+    get statusCode(): number;
+    /**
+     *  The response status message.
+     */
+    get statusMessage(): string;
+    /**
+     *  The response headers. All keys are lower-case.
+     */
+    get headers(): Record<string, string>;
+    /**
+     *  The response body, or ``null`` if there was no body.
+     */
+    get body(): null | Readonly<Uint8Array>;
+    /**
+     *  The response body as a UTF-8 encoded string, or the empty
+     *  string (i.e. ``""``) if there was no body.
+     *
+     *  An error is thrown if the body is invalid UTF-8 data.
+     */
+    get bodyText(): string;
+    /**
+     *  The response body, decoded as JSON.
+     *
+     *  An error is thrown if the body is invalid JSON-encoded data
+     *  or if there was no body.
+     */
+    get bodyJson(): any;
+    [Symbol.iterator](): Iterator<[key: string, value: string]>;
+    constructor(statusCode: number, statusMessage: string, headers: Readonly<Record<string, string>>, body: null | Uint8Array, request?: FetchRequest);
+    /**
+     *  Return a Response with matching headers and body, but with
+     *  an error status code (i.e. 599) and %%message%% with an
+     *  optional %%error%%.
+     */
+    makeServerError(message?: string, error?: Error): FetchResponse;
+    /**
+     *  If called within a [request.processFunc](FetchRequest-processFunc)
+     *  call, causes the request to retry as if throttled for %%stall%%
+     *  milliseconds.
+     */
+    throwThrottleError(message?: string, stall?: number): never;
+    /**
+     *  Get the header value for %%key%%, ignoring case.
+     */
+    getHeader(key: string): string;
+    /**
+     *  Returns true of the response has a body.
+     */
+    hasBody(): this is (FetchResponse & {
+        body: Uint8Array;
+    });
+    /**
+     *  The request made for this response.
+     */
+    get request(): null | FetchRequest;
+    /**
+     *  Returns true if this response was a success statusCode.
+     */
+    ok(): boolean;
+    /**
+     *  Throws a ``SERVER_ERROR`` if this response is not ok.
+     */
+    assertOk(): void;
+}
+//# sourceMappingURL=fetch.d.ts.map

package/lib.commonjs/utils/fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch.d.ts","sourceRoot":"","sources":["../../src.ts/utils/fetch.ts"],"names":[],"mappings":"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"}