@cubicweb/client 3.0.0-alpha.9 → 3.0.0

package/src/api/authenticators/SignedRequestAuthenticator.ts

@@ -0,0 +1,133 @@
+import { AuthenticatedRequest, Authenticator } from "../../Authenticator.js";
+import { encodeFormData } from "../../encodeFormData.js";
+
+export interface SignedRequestAuthToken {
+  /**
+   * id of the token
+   */
+  id: string;
+  /**
+   * secret value of the token
+   */
+  token: string;
+}
+
+function bytesToHex(hashBuffer: ArrayBuffer) {
+  const hashArray = Array.from(new Uint8Array(hashBuffer)); // convert buffer to byte array
+  const hashHex = hashArray
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join(""); // convert bytes to hex string
+  return hashHex;
+}
+
+/**
+ * Authenticator allowing to authenticate requests made to a cubicweb instance
+ * with the [signedrequest](https://forge.extranet.logilab.fr/cubicweb/cubes/signedrequest) cube (v3.x).
+ *
+ * @param token A {@link SignedRequestAuthToken}. This token must be enabled.
+ */
+export class SignedRequestAuthenticator implements Authenticator {
+  private cachedCryptoKey?: CryptoKey;
+
+  constructor(private token: SignedRequestAuthToken) {}
+
+  private async digestBody(body: Uint8Array): Promise<string> {
+    const contentHash = await crypto.subtle.digest("SHA-512", body);
+    const hashHex = bytesToHex(contentHash);
+    return hashHex;
+  }
+
+  private async encodeBody(
+    body: RequestInit["body"]
+  ): Promise<{ body: Uint8Array | null; headers: Headers }> {
+    if (typeof body === "string") {
+      return {
+        body: new TextEncoder().encode(body),
+        headers: new Headers(),
+      };
+    } else if (body instanceof FormData) {
+      return await encodeFormData(body);
+    } else if (body == null) {
+      return {
+        body: null,
+        headers: new Headers(),
+      };
+    } else {
+      throw new Error("Unexpected body type.");
+    }
+  }
+
+  private async getCryptoKey() {
+    if (this.cachedCryptoKey) {
+      return this.cachedCryptoKey;
+    }
+
+    const textEncoder = new TextEncoder();
+    this.cachedCryptoKey = await crypto.subtle.importKey(
+      "raw",
+      textEncoder.encode(this.token.token),
+      {
+        name: "HMAC",
+        hash: "SHA-512",
+      },
+      false,
+      ["sign"]
+    );
+    return this.cachedCryptoKey;
+  }
+
+  /**
+   * Compute headers used to sign the request and encode the content as bytes
+   */
+  private async prepareRequest(
+    url: string,
+    init: RequestInit
+  ): Promise<{ contentToSign: string; headers: Headers }> {
+    const headers = new Headers(init?.headers);
+    const { body: encodedBody, headers: encodingHeaders } =
+      await this.encodeBody(init.body || null);
+    init.body = encodedBody;
+    encodingHeaders.forEach((value, name) => headers.append(name, value));
+
+    const bodyBytes = encodedBody ?? new Uint8Array();
+
+    const bodyHash = await this.digestBody(bodyBytes);
+    headers.append("Content-SHA512", bodyHash);
+
+    const date = new Date();
+    headers.append("X-Cubicweb-Date", date.toUTCString());
+
+    return {
+      contentToSign:
+        (init?.method ?? "GET") +
+        url +
+        bodyHash +
+        (headers.get("Content-Type") ?? "") +
+        (headers.get("X-Cubicweb-Date") ?? ""),
+      headers,
+    };
+  }
+
+  private async signContent(contentToSign: string): Promise<ArrayBuffer> {
+    const textEncoder = new TextEncoder();
+    return await crypto.subtle.sign(
+      "HMAC",
+      await this.getCryptoKey(),
+      textEncoder.encode(contentToSign)
+    );
+  }
+
+  async authenticate(
+    url: string,
+    init: RequestInit
+  ): Promise<AuthenticatedRequest> {
+    const { contentToSign, headers } = await this.prepareRequest(url, init);
+    headers.append(
+      "Authorization",
+      `Cubicweb ${this.token.id}:${bytesToHex(
+        await this.signContent(contentToSign)
+      )}`
+    );
+    return { url, init: { ...init, headers } };
+  }
+}

package/src/api/binary/RQLBinary.ts

@@ -0,0 +1,9 @@
+import { v4 as uuidv4 } from "uuid";
+
+export class RQLBinary {
+  public readonly uuid: string;
+
+  constructor(public readonly blob: Blob) {
+    this.uuid = uuidv4();
+  }
+}

package/src/api/query/RQLQuery.ts

@@ -0,0 +1,51 @@
+import { v4 as uuidv4 } from "uuid";
+import { RQLQueryCellRef, RQLQueryRowRef } from "./references.js";
+import { RQLQueryParams } from "../Api.js";
+
+/**
+ * Class representing a RQL query to be sent to the API.
+ *
+ * Queries are identified by a uuid and are independent from transactions.
+ *
+ * If a query has been used in a transaction, RQLQuery objects can easily retrieve
+ * a reference to the query for later resolving the values in a {@link TransactionResult}.
+ *
+ * @category Api
+ */
+export class RQLQuery {
+  public readonly queryUUID: string;
+
+  /**
+   * Class representing a RQL query to be sent to the API.
+   *
+   * Queries are identified by a uuid and are independent from transactions.
+   *
+   * If a query has been used in a transaction, RQLQuery objects can easily retrieve
+   * a reference to the query for later resolving the values in a {@link TransactionResult}.
+   *
+   * @param rql The rql query
+   * @param params The parameters for the rql query
+   *
+   * @category Api
+   */
+  constructor(
+    public readonly rql: string,
+    public readonly params: RQLQueryParams = {}
+  ) {
+    this.queryUUID = uuidv4();
+  }
+
+  /**
+   * @returns A reference to a {@link ResultSetRow} in the result of this query.
+   */
+  rowRef(row: number): RQLQueryRowRef {
+    return new RQLQueryRowRef(this.queryUUID, row);
+  }
+
+  /**
+   * @returns A reference to a {@link ResultSetCell} in the result of this query.
+   */
+  cellRef(row: number, column: number | string): RQLQueryCellRef {
+    return new RQLQueryCellRef(this.queryUUID, row, column);
+  }
+}

package/src/api/query/references.ts

@@ -0,0 +1,43 @@
+/**
+ * Class representing a reference to a {@link ResultSetRow} in the result of a {@link RQLQuery}.
+ *
+ * Use this to resolve a {@link ResultSetRow} of the referenced {@link RQLQuery}
+ * from a {@link TransactionResult}.
+ *
+ * @category Api
+ */
+export class RQLQueryRowRef {
+  constructor(public readonly queryUUID: string, public readonly row: number) {}
+
+  /**
+   * Retrieve a reference to the given column in this row.
+   *
+   * @param c The column to get a reference for
+   * @returns A reference to the given column in the current row
+   *
+   * @category Api
+   */
+  column(c: number | string): RQLQueryCellRef {
+    return new RQLQueryCellRef(this.queryUUID, this.row, c);
+  }
+}
+
+/**
+ * Class representing a reference to a {@link ResultSetCell} in the result of a {@link RQLQuery}.
+ *
+ * Use this to resolve a {@link ResultSetCell} of the referenced {@link RQLQuery}
+ * from a {@link TransactionResult}.
+ *
+ * This reference can also be used in parameters of other {@link RQLQuery}.
+ * If both {@link RQLQuery} are used in the same {@link RQLQuery},
+ * then the resolved value from the first query will be used in the second.
+ *
+ * @category Api
+ */
+export class RQLQueryCellRef {
+  constructor(
+    public readonly queryUUID: string,
+    public readonly row: number,
+    public readonly column: number | string
+  ) {}
+}

package/src/api/transaction/Transaction.ts

@@ -0,0 +1,31 @@
+import { RQLQuery } from "../query/RQLQuery.js";
+
+/**
+ * Class representing a set of {@link RQLQuery} executed one after the other in a single HTTP request.
+ *
+ * These {@link RQLQuery} can be linked together by using a {@link RQLQueryCellRef}
+ * of one {@link RQLQuery} in the parameters of a subsequent {@link RQLQuery}.
+ *
+ * Binary files are global to the transaction and can be referenced using a {@link RQLQueryBinaryRef}
+ * in the parameters of a {@link RQLQuery}.
+ */
+export class Transaction {
+  private _queries: Array<RQLQuery> = [];
+
+  /**
+   * Adds the given queries to the transaction.
+   *
+   * Each {@link RQLQuery} will be executed one after the other.
+   * These {@link RQLQuery} can be linked together by using a {@link RQLQueryCellRef}
+   * of one {@link RQLQuery} in the parameters of a subsequent {@link RQLQuery}.
+   *
+   * @param queries New queries to add to the transaction
+   */
+  push(...queries: RQLQuery[]): void {
+    this._queries.push(...queries);
+  }
+
+  get queries(): ReadonlyArray<RQLQuery> {
+    return this._queries;
+  }
+}

package/src/api/transaction/TransactionResult.ts

@@ -0,0 +1,68 @@
+import { getQueryIndexInTransaction } from "../../utils.js";
+import {
+  RawResultSet,
+  ResultSet,
+  ResultSetCell,
+  ResultSetRow,
+} from "../ResultSet.js";
+import { RQLQuery } from "../query/RQLQuery.js";
+import { RQLQueryCellRef, RQLQueryRowRef } from "../query/references.js";
+import { Transaction } from "./Transaction.js";
+
+/**
+ * Interface representing the json returned by the API when executing
+ * a Transaction
+ *
+ * @category Api
+ */
+export interface RawTransactionResult {
+  readonly result_sets: RawResultSet[];
+}
+
+/**
+ * Class representing the result of a transaction.
+ *
+ * Retrieving the values is done using query references.
+ *
+ * @example
+ *
+ * Retrieving the first value in a result set
+ *
+ * ```tsx
+ * const transaction = new Transaction()
+ * const query = new RQLQuery("Any X WHERE X name 'test'", {})
+ * transaction.push(query)
+ * const result = client.executeTransaction(transaction)
+ * const eid = result.resolve(query.cellRef(0, 0))
+ * ```
+ *
+ * @category Api
+ */
+export class TransactionResult {
+  private rawResultSets: RawResultSet[];
+
+  constructor(
+    private transaction: Transaction,
+    rawTransactionResult: RawTransactionResult
+  ) {
+    this.rawResultSets = rawTransactionResult.result_sets;
+  }
+
+  getResultSet(query: RQLQuery): ResultSet {
+    const index = getQueryIndexInTransaction(this.transaction, query.queryUUID);
+    const resultSet = new ResultSet(this.rawResultSets[index]);
+    return resultSet;
+  }
+
+  getRow(ref: RQLQueryRowRef): ResultSetRow {
+    const index = getQueryIndexInTransaction(this.transaction, ref.queryUUID);
+    const resultSet = new ResultSet(this.rawResultSets[index]);
+    return resultSet.getRow(ref.row);
+  }
+
+  getCell(ref: RQLQueryCellRef): ResultSetCell {
+    const index = getQueryIndexInTransaction(this.transaction, ref.queryUUID);
+    const resultSet = new ResultSet(this.rawResultSets[index]);
+    return resultSet.getCell(ref.row, ref.column);
+  }
+}

package/src/encodeFormData.ts

@@ -0,0 +1,126 @@
+// Adapted from https://github.com/axios/axios/blob/c6cce43cd94489f655f4488c5a50ecaf781c94f2/lib/helpers/formDataToStream.js#L92
+// See https://andreubotella.github.io/multipart-form-data/ for spec and algorithm description
+
+const ALPHA = "abcdefghijklmnopqrstuvwxyz";
+const BOUNDARY_ALPHABET = ALPHA + ALPHA.toUpperCase() + "0123456789" + "-_";
+
+const textEncoder = new TextEncoder();
+
+const CRLF = "\r\n";
+const CRLF_BYTES = textEncoder.encode(CRLF);
+const CRLF_BYTES_COUNT = 2;
+
+class FormDataPart {
+  private headers: Uint8Array;
+  private contentLength: number;
+  public readonly size: number;
+  name: string;
+  value: Uint8Array | File;
+  constructor(name: string, value: FormDataEntryValue) {
+    const { escapeName } = FormDataPart;
+
+    let headers = `Content-Disposition: form-data; name="${escapeName(name)}"${
+      !(typeof value === "string") && value.name
+        ? `; filename="${escapeName(value.name)}"`
+        : ""
+    }${CRLF}`;
+    let bytesOrFile: Uint8Array | File;
+    if (typeof value === "string") {
+      bytesOrFile = textEncoder.encode(
+        String(value).replace(/\r?\n|\r\n?/g, CRLF)
+      );
+      this.contentLength = bytesOrFile.byteLength;
+    } else {
+      bytesOrFile = value;
+      headers += `Content-Type: ${
+        value.type || "application/octet-stream"
+      }${CRLF}`;
+      this.contentLength = bytesOrFile.size;
+    }
+
+    this.headers = textEncoder.encode(headers + CRLF);
+
+    this.size = this.headers.byteLength + this.contentLength + CRLF_BYTES_COUNT;
+
+    this.name = name;
+    this.value = bytesOrFile;
+  }
+
+  async *encode(): AsyncGenerator<Uint8Array> {
+    yield this.headers;
+
+    const { value } = this;
+
+    if (value instanceof Uint8Array) {
+      yield value;
+    } else {
+      yield new Uint8Array(await value.arrayBuffer());
+    }
+
+    yield CRLF_BYTES;
+  }
+
+  static escapeName(name: string): string {
+    return String(name).replace(
+      /[\r\n"]/g,
+      (match) =>
+        ({
+          "\r": "%0D",
+          "\n": "%0A",
+          '"': "%22",
+        }[match as "\r" | "\n" | '"'])
+    );
+  }
+}
+
+function generateBoundary(): string {
+  let str = "";
+  const { length } = BOUNDARY_ALPHABET;
+  let size = 25;
+  while (size--) {
+    str += BOUNDARY_ALPHABET[(Math.random() * length) | 0];
+  }
+
+  return str;
+}
+
+export async function encodeFormData(body: FormData) {
+  const tag = "form-data-boundary";
+  const boundary = tag + "-" + generateBoundary();
+
+  const boundaryBytes = textEncoder.encode("--" + boundary + CRLF);
+  const footerBytes = textEncoder.encode("--" + boundary + "--" + CRLF + CRLF);
+  let contentLength = footerBytes.byteLength;
+
+  const parts = Array.from(body.entries()).map(([name, value]) => {
+    const part = new FormDataPart(name, value);
+    contentLength += part.size;
+    return part;
+  });
+
+  contentLength += boundaryBytes.byteLength * parts.length;
+
+  const computedHeaders = new Headers({
+    "Content-Type": `multipart/form-data; boundary=${boundary}`,
+  });
+
+  if (Number.isFinite(contentLength)) {
+    computedHeaders.append("Content-Length", contentLength.toString());
+  }
+
+  const fullContent = new Uint8Array(contentLength);
+  let offset = 0;
+
+  for (const part of parts) {
+    fullContent.set(boundaryBytes, offset);
+    offset += boundaryBytes.length;
+
+    for await (const arr of part.encode()) {
+      fullContent.set(arr, offset);
+      offset += arr.length;
+    }
+  }
+  fullContent.set(footerBytes, offset);
+
+  return { body: fullContent, headers: computedHeaders };
+}

package/src/{Errors.ts → errors.ts}

@@ -1,3 +1,6 @@
+/**
+ * There was an error processing the CubicWeb schema.
+ */
 export class InconsistentSchemaError extends Error {
   constructor(message: string) {
     super(`Inconsistent schema: ${message}`);
@@ -5,16 +8,12 @@ export class InconsistentSchemaError extends Error {
   }
 }
 
+/**
+ * There was an error while validating the data sent to the server.
+ */
 export class ValidationError extends Error {
   constructor(message: string) {
     super(message);
     Object.setPrototypeOf(this, new.target.prototype);
   }
 }
-
-export class TransactionClosedError extends Error {
-  constructor() {
-    super("Trying to use a closed transaction");
-    Object.setPrototypeOf(this, new.target.prototype);
-  }
-}

package/src/index.ts

@@ -1,25 +1,32 @@
 // Raw Schema
-export * from "./schema/raw/Constraints";
-export * from "./schema/raw/Entities";
-export * from "./schema/raw/RelationDefinitions";
-export * from "./schema/raw/Schema";
-export * from "./schema/raw/Utils";
+export * from "./schema/raw/Constraints.js";
+export * from "./schema/raw/Entities.js";
+export * from "./schema/raw/RelationDefinitions.js";
+export * from "./schema/raw/Schema.js";
+export * from "./schema/raw/Utils.js";
 
 // Schema Abstraction class
-export * from "./schema/classes/EntitySchema";
-export * from "./schema/classes/RelationDefinitionSchema";
-export * from "./schema/classes/Schema";
-export * from "./schema/classes/Utils";
+export * from "./schema/classes/EntitySchema.js";
+export * from "./schema/classes/RelationDefinitionSchema.js";
+export * from "./schema/classes/Schema.js";
+export * from "./schema/classes/Utils.js";
 
-export * from "./Errors";
+export * from "./errors.js";
 
 // API
-export { default as Client } from "./api/Client";
-export * from "./api/Transaction";
 export {
-  RQLQuery,
-  RQLParams,
-  RqlRow,
-  ResultSet,
+  RQLQueryParamValue,
+  RQLQueryParams,
   ApiErrorResponse,
-} from "./api/Api";
+  CurrentUser,
+} from "./api/Api.js";
+export { ResultSet, ResultSetRow, ResultSetCell } from "./api/ResultSet.js";
+export { default as Client, ClientOptions } from "./api/Client.js";
+export { Transaction } from "./api/transaction/Transaction.js";
+export { TransactionResult } from "./api/transaction/TransactionResult.js";
+export { RQLQuery } from "./api/query/RQLQuery.js";
+export { RQLBinary } from "./api/binary/RQLBinary.js";
+export { RQLQueryRowRef, RQLQueryCellRef } from "./api/query/references.js";
+
+// Authenticators
+export { Authenticator } from "./Authenticator.js";

package/src/schema/classes/EntitySchema.ts

@@ -1,8 +1,11 @@
-import { EntityRawSchemaArray } from "../raw/Entities";
-import { RelationDefinitionRawSchemaArray } from "../raw/RelationDefinitions";
-import { RelationDefinitionSchema } from "./RelationDefinitionSchema";
-import { Schema } from "./Schema";
-import { MatchedRelationDefinition, RelationDefinitionMatcher } from "./Utils";
+import { EntityRawSchemaArray } from "../raw/Entities.js";
+import { RelationDefinitionRawSchemaArray } from "../raw/RelationDefinitions.js";
+import { RelationDefinitionSchema } from "./RelationDefinitionSchema.js";
+import { Schema } from "./Schema.js";
+import {
+  MatchedRelationDefinition,
+  RelationDefinitionMatcher,
+} from "./Utils.js";
 
 /**
  * Wrapper around raw entity schemas from the Schema.

package/src/schema/classes/RelationDefinitionSchema.ts

@@ -1,13 +1,13 @@
-import { InconsistentSchemaError } from "../../Errors";
-import { EntityRawSchemaArray } from "../raw/Entities";
+import { InconsistentSchemaError } from "../../errors.js";
+import { EntityRawSchemaArray } from "../raw/Entities.js";
 import {
   RelationDefinitionRawSchemaArray,
   Cardinality,
-} from "../raw/RelationDefinitions";
-import { IsLooseSchema, EntityRawSchemaByType } from "../raw/Utils";
-import { EntitySchema } from "./EntitySchema";
-import { Schema } from "./Schema";
-import { EntityRole, isCardinalityRequired } from "./Utils";
+} from "../raw/RelationDefinitions.js";
+import { IsLooseSchema, EntityRawSchemaByType } from "../raw/Utils.js";
+import { EntitySchema } from "./EntitySchema.js";
+import { Schema } from "./Schema.js";
+import { EntityRole, isCardinalityRequired } from "./Utils.js";
 
 /**
  * Wrapper around raw relation definition schemas from the Schema.

package/src/schema/classes/Schema.ts

@@ -1,17 +1,20 @@
-import { EntityRawSchemaArray } from "../raw/Entities";
+import { EntityRawSchemaArray } from "../raw/Entities.js";
 import {
   RelationDefinitionRawSchema,
   RelationDefinitionRawSchemaArray,
-} from "../raw/RelationDefinitions";
-import { RawSchema } from "../raw/Schema";
+} from "../raw/RelationDefinitions.js";
+import { RawSchema } from "../raw/Schema.js";
 import {
   EntityRawSchemaByType,
   IsETypeInStrictSchema,
   IsLooseSchema,
-} from "../raw/Utils";
-import { EntitySchema } from "./EntitySchema";
-import { RelationDefinitionSchema } from "./RelationDefinitionSchema";
-import { RelationDefinitionMatcher, MatchedRelationDefinition } from "./Utils";
+} from "../raw/Utils.js";
+import { EntitySchema } from "./EntitySchema.js";
+import { RelationDefinitionSchema } from "./RelationDefinitionSchema.js";
+import {
+  RelationDefinitionMatcher,
+  MatchedRelationDefinition,
+} from "./Utils.js";
 
 const rawSchemaKey: unique symbol = Symbol("Indexer of the rawSchema");
 

package/src/schema/classes/Utils.ts

@@ -1,11 +1,11 @@
-import { EntityRawSchemaArray } from "../raw/Entities";
+import { EntityRawSchemaArray } from "../raw/Entities.js";
 import {
   Cardinality,
   RelationDefinitionRawSchema,
   RelationDefinitionRawSchemaArray,
-} from "../raw/RelationDefinitions";
-import { Schema } from "./Schema";
-import { EntitySchema } from "./EntitySchema";
+} from "../raw/RelationDefinitions.js";
+import { Schema } from "./Schema.js";
+import { EntitySchema } from "./EntitySchema.js";
 
 // This prefix is often applied to relation types as convention
 // indicating a relation is viewed from the object's point of view