BufferPrimitiveCollection: Material API

Author: donmccurdy

.github/actions/update-tokens/.gitignore

@@ -0,0 +1,3 @@
+node_modules
+package-lock.json
+.env

.github/actions/update-tokens/README.md

@@ -0,0 +1,23 @@
+# Update tokensin CI
+
+The purpose of this "sub-project" is to automate our update of access tokens and keys that we include with the release and deployment of CesiumJS and Sandcastle.
+
+Our general policy for access tokens and keys is that **they should work for two releases of CesiumJS**, ie 2 months.
+
+The main work happens in `index.js` and the list of "replacements" is defined in `replacements.js`. If you want to add new replacements they should go in `replacements.js`. Each replacement relies on the file path containing the token, an [esquery "js selector"](https://estools.github.io/esquery/) (see [AST Explorer](https://astexplorer.net/) for help) and a value or function to define the new value.
+
+The main update logic is scheduled to happen in CI with the [`update-tokens`](../../workflows/update-tokens.yml) workflow. This lets us define the necessary access secrets in Github's settings.
+
+Access tokens in ion do not automatically expire like share keys do in the itwin platform. To account for this we have a separate `ionTokenDeleter.js` script to handle deleting tokens. This is meant to run in the [`prod`](../../workflows/prod.yml) workflow _after_ the normal release process is done.
+
+## Running locally
+
+The scripts rely on a few environment variables. The easiest way to set these up is using `dotenvx`. Create a `.env` file in this directory and populate it with the following values.
+
+```sh
+ITWIN_SERVICE_APP_CLIENT_ID=[client id]
+ITWIN_SERVICE_APP_CLIENT_SECRET=[client secret]
+ION_TOKEN_CONTROLLER_TOKEN=[ion token with scopes: tokens:read, tokens:write]
+```
+
+Then you can just run `npx dotenvx run -- node index.js` and it will pull in the appropriate values.

.github/actions/update-tokens/iTwinShareUpdater.js

@@ -0,0 +1,233 @@
+import { add, getMonth, setDate } from "date-fns";
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { exit } from "node:process";
+import { fileURLToPath } from "node:url";
+
+const CLIENT_ID = process.env.ITWIN_SERVICE_APP_CLIENT_ID;
+const CLIENT_SECRET = process.env.ITWIN_SERVICE_APP_CLIENT_SECRET;
+
+if (!CLIENT_ID || !CLIENT_SECRET) {
+  console.error("Missing client id or secret");
+  exit(1);
+}
+
+const IMS_URL = "https://ims.bentley.com";
+const ITWIN_API_URL = "https://api.bentley.com";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const projectRoot = join(__dirname, "../../../");
+const packageJsonPath = join(projectRoot, "package.json");
+
+async function getCurrentMinorVersion() {
+  const data = await readFile(packageJsonPath, "utf8");
+  const { version } = JSON.parse(data);
+  const majorMinor = version.match(/^(.*)\.(.*)\./);
+  const minor = Number(majorMinor[2]);
+  return minor;
+}
+
+/**
+ * @typedef {object} Share
+ * @property {string} id
+ * @property {string} iTwinId
+ * @property {string} shareKey
+ * @property {string} shareContract
+ * @property {string} expiration ISO date string
+ */
+
+/**
+ * @typedef {object} Itwin
+ * @property {string} id
+ * @property {string} class
+ * @property {string} subClass
+ * @property {string | null} type
+ * @property {string} number
+ * @property {string} displayName
+ * @property {string} status
+ */
+
+/**
+ * @param {string} clientId
+ * @param {string} clientSecret
+ * @returns {Promise<string>}
+ */
+async function getIMSToken(clientId, clientSecret) {
+  const resp = await fetch(`${IMS_URL}/connect/token`, {
+    method: "POST",
+    body: new URLSearchParams({
+      grant_type: "client_credentials",
+      client_id: clientId,
+      client_secret: clientSecret,
+      scope: "itwin-platform",
+    }),
+  });
+
+  if (!resp.ok) {
+    const result = await resp.json();
+    throw new Error(
+      `Error fetching token from IMS. Status: ${resp.status}. ${result.error} - ${result.error_description}`,
+    );
+  }
+
+  const result = await resp.json();
+  return result.access_token;
+}
+
+/**
+ * @param {string} itwinId
+ * @param {string} accessToken
+ * @returns {Promise<Share[]>}
+ */
+async function getShares(itwinId, accessToken) {
+  const resp = await fetch(
+    `${ITWIN_API_URL}/accesscontrol/itwins/${itwinId}/shares`,
+    {
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+        Accept: "application/vnd.bentley.itwin-platform.v2+json",
+      },
+    },
+  );
+
+  if (!resp.ok) {
+    throw new Error(
+      `Error getting iTwin shares for ${itwinId}. Status: ${resp.status}`,
+    );
+  }
+
+  const result = await resp.json();
+  return result.shares;
+}
+
+/**
+ * The iTwin API doesn't provide any way to save metadata with a share key.
+ * We would like a way to match keys to release versions to avoid creating duplicates
+ * or deleting keys that may still be in use. This could be because the GH job was re-run
+ * or we do a patch release where the key doesn't have to change
+ *
+ * @param {Share[]} shares
+ * @param {number} currentMajorVersion
+ */
+function mapSharesToVersion(shares, currentMajorVersion) {
+  // Tokens should last for 2 releases per our Release Guide/cycle
+  // If current version is 1.139 and it's 2026-03-25
+  // 1.138 should expire 2026-04-01   Current month + 1 === currentVersion - 1 (nextToExpire)
+  // 1.139 should expire 2026-05-01   Current month + 2 === currentVersion     (nextToExpire + 1)
+  // 1.140 should expire 2026-06-01   Current month + 3 === currentVersion + 1 (nextToExpire + 2)
+
+  const today = new Date();
+
+  const nextToExpire = currentMajorVersion - 1;
+  /** @type {Record<number, Share>} */
+  const keyPerVersion = {};
+  for (const share of shares) {
+    const expiration = new Date(share.expiration);
+    const monthsApart = getMonth(expiration) - getMonth(today);
+    if (monthsApart === 0) {
+      throw new Error("Unknown version for share key");
+    }
+    const forVersion = nextToExpire + monthsApart - 1;
+    if (keyPerVersion[forVersion]) {
+      throw new Error("Found multiple keys per version");
+    }
+    keyPerVersion[forVersion] = share;
+  }
+  return keyPerVersion;
+}
+
+/**
+ * @param {string} itwinId
+ * @param {string} contractName Should be "SandCastle"
+ * @param {string} expiration
+ * @param {string} accessToken
+ * @returns {Promise<Share>}
+ */
+async function createShare(itwinId, contractName, expiration, accessToken) {
+  const resp = await fetch(
+    `${ITWIN_API_URL}/accesscontrol/itwins/${itwinId}/shares`,
+    {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+        Accept: "application/vnd.bentley.itwin-platform.v2+json",
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        shareContract: contractName,
+        // setting this to null will default to the max length. For the SandCastle contract that's 365 days
+        expiration: expiration,
+      }),
+    },
+  );
+
+  if (!resp.ok) {
+    throw new Error(
+      `Error creating iTwin share for ${itwinId}. Status: ${resp.status}`,
+    );
+  }
+
+  const result = await resp.json();
+
+  return result.share;
+}
+
+/**
+ * Store a single access token to reuse for subsequent requests sisnce we have multiple itwins
+ * @type {string | undefined}
+ */
+let accessToken;
+/** @type {Record<string, string>} */
+const cacheKeysPerItwin = {};
+
+/**
+ * @param {string} itwinId
+ */
+export async function getNewKeyForItwin(itwinId) {
+  if (cacheKeysPerItwin[itwinId]) {
+    console.log("  already generated for this itwin, reusing");
+    // no need to go through the whole process of checking/generating for the same itwin
+    return cacheKeysPerItwin[itwinId];
+  }
+
+  if (accessToken === undefined) {
+    accessToken = await getIMSToken(CLIENT_ID, CLIENT_SECRET);
+  }
+
+  const existingShares = await getShares(itwinId, accessToken);
+  const currentVersion = await getCurrentMinorVersion();
+  const nextVersion = currentVersion + 1;
+  const sharePerVersion = mapSharesToVersion(existingShares, currentVersion);
+
+  console.log(
+    "  creating new key for version",
+    nextVersion,
+    "for itwin",
+    itwinId,
+  );
+
+  if (sharePerVersion[nextVersion]) {
+    console.log("  found existing key for version", nextVersion, "reusing it");
+    cacheKeysPerItwin[itwinId] = sharePerVersion[nextVersion].shareKey;
+    // If a share key already exists for the target version then just reuse it
+    return sharePerVersion[nextVersion].shareKey;
+  }
+
+  console.log("Generating new key for itwin", itwinId);
+  const maxAllowedForContract = 10;
+  if (existingShares.length >= maxAllowedForContract - 1) {
+    throw new Error(`This itwin has too many share keys: ${itwinId}`);
+  }
+
+  const expiration = setDate(add(new Date(), { months: 3 }), 1);
+  const newShare = await createShare(
+    itwinId,
+    "SandCastle",
+    expiration.toISOString(),
+    accessToken,
+  );
+
+  console.log("  new key generated");
+  cacheKeysPerItwin[itwinId] = newShare.shareKey;
+  return newShare.shareKey;
+}

.github/actions/update-tokens/index.js

@@ -0,0 +1,131 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { parse, print } from "recast";
+import * as espree from "espree";
+import * as prettier from "prettier";
+import * as babelPlugin from "prettier/plugins/babel";
+import * as estreePlugin from "prettier/plugins/estree";
+import esquery from "esquery";
+import { getReplacements } from "./replacements.js";
+import yargs from "yargs";
+import { hideBin } from "yargs/helpers";
+
+/** @import {Replacement, NewValueFunction} from './replacements.js' */
+
+const argv = await yargs(hideBin(process.argv))
+  .options({
+    update: {
+      type: "boolean",
+      description:
+        "Use to force an update. By default this will behave as a dry run and replace with placeholders",
+    },
+  })
+  .help(false)
+  .version(false)
+  .strict()
+  .parse();
+
+/**
+ * Replace the value of a variable assignment's literal in an AST
+ *
+ * @param {object} ast Full AST for the file being processed
+ * @param {string} selector an esquery selector to the literal to change
+ * @param {string | NewValueFunction | undefined} newValue the new value to set
+ */
+async function replaceVariableValue(ast, selector, newValue) {
+  if (!ast) {
+    throw new Error("Missing ast");
+  }
+  if (!selector) {
+    throw new Error("Missing selector");
+  }
+  if (!newValue) {
+    throw new Error("Missing newValue");
+  }
+
+  const foundNodes = esquery.query(ast, selector);
+  if (!foundNodes || foundNodes.length === 0) {
+    throw new Error(`Unable to find node for selector: ${selector}`);
+  }
+  if (foundNodes.length > 1) {
+    console.error("selected", foundNodes);
+    throw new Error(
+      `Found too many nodes for selector: ${selector}. See above for the nodes selected`,
+    );
+  }
+
+  if (foundNodes[0].type !== "Literal") {
+    console.error(foundNodes[0]);
+    throw new Error(
+      "Selected node that is not a Literal. See above for the node that was selected",
+    );
+  }
+
+  if (!argv.update) {
+    console.log("  using fake value for dry-run");
+    foundNodes[0].value = "fake-new-value";
+    return;
+  }
+
+  const existingValue = foundNodes[0].value;
+  try {
+    const actualNewValue =
+      typeof newValue === "function"
+        ? await newValue(`${existingValue}`)
+        : newValue;
+
+    if (actualNewValue === undefined) {
+      // Skip if there is no new value. This can be used in the new value function to indicate no update
+      console.log("  Skipping - no new value provided");
+      return;
+    }
+
+    foundNodes[0].value = actualNewValue;
+  } catch (error) {
+    console.error("Failed to generate new value:");
+    console.error(error);
+    foundNodes[0].value =
+      "Failed to get new value, check the logs for more info";
+  }
+}
+
+/**
+ * Format code with Prettier
+ *
+ * @param {string} code the code to format
+ */
+async function formatCode(code) {
+  const formatted = await prettier.format(code, {
+    parser: "babel",
+    plugins: [babelPlugin, estreePlugin],
+  });
+  return formatted;
+}
+
+/**
+ * Process a replacement for a file. Reads in the file and writes it back out to the same location
+ *
+ * @param {Replacement} replacement The replacement to process
+ */
+async function processReplacement(replacement) {
+  const { filePath, selector, newValue } = replacement;
+  console.log("Processing", filePath);
+  const code = readFileSync(filePath, "utf-8");
+
+  const ast = parse(code, {
+    parser: {
+      parse: (js, opts) => espree.parse(js, { ...opts, ecmaVersion: 2022 }),
+      tokenize: (js, opts) =>
+        espree.tokenize(js, { ...opts, ecmaVersion: 2022 }),
+    },
+  });
+
+  await replaceVariableValue(ast, selector, newValue);
+
+  const output = print(ast).code;
+
+  writeFileSync(filePath, await formatCode(output));
+}
+
+for (const replacement of getReplacements()) {
+  await processReplacement(replacement);
+}