sdk: add evaluateBatch()

options for that method:

- rejectMixed (default false) -- if a mixed result (ie. at least one
  element of the batch failed evaluation) causes a promise rejection
- fallback (default false) -- if a 404 for the batch endpoint should
  degrade transparently into a sequence of single evaluations. This
  would be the case when talking to OPA (not Enterprise OPA).

Signed-off-by: Stephan Renatus <stephan@styra.com>

Author: srenatus

.github/workflows/pull_request.yaml

@@ -16,10 +16,24 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: 21
-      - name: Compile and Test
+      - name: Compile, Lint
         run: |
           npm ci
           npx eslint --config=.eslintrc.styra.cjs --max-warnings=0 src README.md
           npx prettier . --check
           npx typedoc
-          node --import tsx --test tests/**/*.ts
+      - name: Test
+        run: |
+          node --import tsx \
+               --test-reporter=spec \
+               --test-reporter=junit \
+               --test-reporter-destination=stdout \
+               --test-reporter-destination=report.xml \
+               --test tests/**/*.ts
+        env:
+          EOPA_LICENSE_KEY: ${{ secrets.EOPA_LICENSE_KEY }}
+      - name: Publish Test Report
+        uses: mikepenz/action-junit-report@v4
+        if: always()
+        with:
+          report_paths: report.xml

DEVELOPMENT.md

@@ -36,3 +36,9 @@ and with testcontainers-node's debug logging:
 ```shell
 DEBUG='testcontainers*' node --import tsx --test tests/**/*.ts
 ```
+
+Single out a test case by name:
+
+```shell
+node --import tsx --test-name-pattern="can be called with input==false"  --test tests/**/*.ts
+```

src/hooks/request-path-hook.ts

@@ -7,7 +7,10 @@ export class RewriteRequestPathHook implements BeforeCreateRequestHook {
     input: RequestInput,
   ): RequestInput {
     const url = new URL(input.url);
-    if (url.pathname.indexOf("/v1/data/") != -1) {
+    if (
+      url.pathname.indexOf("/v1/data/") != -1 ||
+      url.pathname.indexOf("/v1/batch/data/") != -1
+    ) {
       url.pathname = decodeURIComponent(url.pathname);
       return { ...input, url };
     }

src/opaclient.ts

@@ -1,9 +1,19 @@
 import { OpaApiClient as Opa } from "./sdk/index.js";
-import type { Input, Result } from "./sdk/models/components/index.js";
+import {
+  type Input,
+  type Result,
+  type ResponsesSuccessfulPolicyResponse,
+  type ServerError,
+  BatchMixedResults,
+  BatchSuccessfulPolicyEvaluation,
+  SuccessfulPolicyResponse,
+} from "./sdk/models/components/index.js";
 import {
   ExecutePolicyWithInputResponse,
   ExecutePolicyResponse,
 } from "./sdk/models/operations/index.js";
+import { SDKError } from "./sdk/models/errors/sdkerror.js";
+import { ServerError as ServerError_ } from "./sdk/models/errors/servererror.js";
 import { SDKOptions } from "./lib/config.js";
 import { HTTPClient } from "./lib/http.js";
 import { RequestOptions as FetchOptions } from "./lib/sdks.js";
@@ -37,12 +47,21 @@ export interface RequestOptions<Res> extends FetchOptions {
   fromResult?: (res?: Result) => Res;
 }
 
+/** Extra per-request options for using the high-level SDK's
+ * evaluateBatch method.
+ */
+export interface BatchRequestOptions<Res> extends RequestOptions<Res> {
+  rejectMixed?: boolean; // reject promise if the batch result is "mixed", i.e. if any of the items errored
+  fallback?: boolean; // fall back to sequential evaluate calls if server doesn't support batch API
+}
+
 /** OPAClient is the starting point for using the high-level API.
  *
  * Use {@link Opa} if you need some low-level customization.
  */
 export class OPAClient {
   private opa: Opa;
+  private opaFallback: boolean = false;
 
   /** Create a new `OPA` instance.
    * @param serverURL - The OPA URL, e.g. `https://opa.internal.corp:8443/`.
@@ -96,9 +115,10 @@ export class OPAClient {
       );
     }
     if (!result.successfulPolicyResponse) throw `no result in API response`;
+
     const res = result.successfulPolicyResponse.result;
-    const fromResult = opts?.fromResult;
-    return fromResult ? fromResult(res) : (res as Res);
+    const fromResult = opts?.fromResult || id<Res>;
+    return fromResult(res);
   }
 
   /** `evaluateDefault` is used to evaluate the server's default policy with optional input.
@@ -122,8 +142,126 @@ export class OPAClient {
       opts,
     );
     if (!resp.result) throw `no result in API response`;
-    const res = resp.result;
-    const fromResult = opts?.fromResult;
-    return fromResult ? fromResult(res) : (res as Res);
+
+    const fromResult = opts?.fromResult || id<Res>;
+    return fromResult(resp.result);
+  }
+
+  /** `evaluateBatch` is used to evaluate the policy at the specified path, for a batch of many inputs.
+   *
+   * @param path - The path to the policy, without `/v1/batch/data`: use `authz/allow` to evaluate policy `data.authz.allow`.
+   * @param inputs - The inputs to the policy.
+   * @param opts - Per-request options to control how the policy evaluation result is to be transformed
+   * into `Res` (via `fromResult`), if any failures in the batch result should reject the promose (via
+   * `rejectMixed`), and low-level fetch options.
+   */
+  async evaluateBatch<In extends Input | ToInput, Res>(
+    path: string,
+    inputs: { [k: string]: In },
+    opts?: BatchRequestOptions<Res>,
+  ): Promise<{ [k: string]: Res | ServerError }> {
+    const inps = Object.fromEntries(
+      Object.entries(inputs).map(([k, inp]) => [
+        k,
+        implementsToInput(inp) ? inp.toInput() : inp,
+      ]),
+    );
+    let res: BatchMixedResults | BatchSuccessfulPolicyEvaluation | undefined;
+
+    if (this.opaFallback && opts?.fallback) {
+      // memoized fallback: we have hit a 404 here before
+      const responses = await this.fallbackBatch(path, inps, opts);
+      res = { responses };
+    } else {
+      try {
+        const resp = await this.opa.executeBatchPolicyWithInput(
+          { path, requestBody: { inputs: inps } },
+          opts,
+        );
+
+        res = resp.batchMixedResults || resp.batchSuccessfulPolicyEvaluation;
+      } catch (err) {
+        if (
+          err instanceof SDKError &&
+          err.httpMeta.response.status == 404 &&
+          opts?.fallback
+        ) {
+          this.opaFallback = true;
+          const responses = await this.fallbackBatch(path, inps, opts);
+          res = { responses };
+        } else {
+          throw err;
+        }
+      }
+    }
+
+    if (!res) throw `no result in API response`;
+
+    const entries = [];
+    for (const [k, v] of Object.entries(res?.responses ?? {})) {
+      entries.push([k, await processResult(v, opts)]);
+    }
+    return Object.fromEntries(entries);
   }
+
+  // run a sequence of evaluatePolicyWithInput(), via Promise.all/Promise.allSettled
+  async fallbackBatch<Res>(
+    path: string,
+    inputs: { [k: string]: Input },
+    opts?: BatchRequestOptions<Res>,
+  ): Promise<{ [k: string]: ServerError | SuccessfulPolicyResponse }> {
+    let items: [string, ServerError | SuccessfulPolicyResponse][];
+    const keys = Object.keys(inputs);
+    const ps = Object.values(inputs).map((input) =>
+      this.opa
+        .executePolicyWithInput({ path, requestBody: { input } })
+        .then(({ successfulPolicyResponse: res }) => res),
+    );
+    if (opts?.rejectMixed) {
+      items = await Promise.all(ps).then((results) =>
+        results.map((result, i) => {
+          if (!result) throw `no result in API response`;
+          return [
+            keys[i] as string, // can't be undefined
+            result,
+          ];
+        }),
+      );
+    } else {
+      const settled = await Promise.allSettled(ps).then((results) => {
+        return results.map((res, i) => {
+          if (res.status === "rejected") {
+            return [
+              keys[i],
+              {
+                ...(res.reason as ServerError_).data$,
+                httpStatusCode: "500",
+              },
+            ] as [string, ServerError];
+          }
+          return [keys[i], res.value] as [string, SuccessfulPolicyResponse];
+        });
+      });
+      items = settled;
+    }
+    return Object.fromEntries(items);
+  }
+}
+
+function processResult<Res>(
+  res: ResponsesSuccessfulPolicyResponse | ServerError,
+  opts?: BatchRequestOptions<Res>,
+): Promise<Res | ServerError> {
+  if (res && "code" in res) {
+    if (opts?.rejectMixed) return Promise.reject(res as ServerError);
+
+    return Promise.resolve(res as ServerError);
+  }
+
+  const fromResult = opts?.fromResult || id<Res>;
+  return Promise.resolve(fromResult(res.result));
+}
+
+function id<T>(x: any): T {
+  return x as T;
 }