@paulhectork/aiiinotate 0.12.0

package/src/utils/iiif2Utils.js

@@ -0,0 +1,332 @@
+import { v4 as uuid4 } from "uuid";
+
+import { maybeToArray, getHash, isNullish, isObject, xywhToInt, objectHasKey, visibleLog } from "#utils/utils.js";
+import { IIIF_PRESENTATION_2, IIIF_PRESENTATION_2_CONTEXT } from "#utils/iiifUtils.js";
+import { svgStringToXywh } from "#utils/svg.js";
+import { PUBLIC_URL } from "#constants";
+import logger from "#utils/logger.js";
+
+/** @typedef {import("#types").MongoCollectionType} MongoCollectionType */
+
+// IIIF PRESENTATION 2.1 RECOMMENDED URI PATTERNS https://iiif.io/api/presentation/2.1/#a-summary-of-recommended-uri-patterns
+//
+// Collection 	             {scheme}://{host}/{prefix}/collection/{name}
+// Manifest 	               {scheme}://{host}/{prefix}/{identifier}/manifest
+// Sequence 	               {scheme}://{host}/{prefix}/{identifier}/sequence/{name}
+// Canvas 	                 {scheme}://{host}/{prefix}/{identifier}/canvas/{name}
+// Annotation (incl images)  {scheme}://{host}/{prefix}/{identifier}/annotation/{name}
+// AnnotationList            {scheme}://{host}/{prefix}/{identifier}/list/{name}
+// Range 	                   {scheme}://{host}/{prefix}/{identifier}/range/{name}
+// Layer 	                   {scheme}://{host}/{prefix}/{identifier}/layer/{name}
+// Content 	                 {scheme}://{host}/{prefix}/{identifier}/res/{name}.{format}
+
+/**
+ * extract a manifest's short ID from a IIIF URI.
+ * NOTE if the `iiifUri` doesn' follow IIIF 2.x  recommendations, the quality of geneated IDs is really degraded : 2 canvases URI from the same manifest will generate a different hash.
+ * inspired by : https://github.com/glenrobson/SimpleAnnotationServer/blob/dc7c8c6de9f4693c678643db2a996a49eebfcbb0/src/main/java/uk/org/llgc/annotation/store/data/Manifest.java#L123C16-L123C26
+ * @param {string} iiifUri
+ * @returns {string}
+ */
+const getManifestShortId = (iiifUri) => {
+  const keywords = [ "manifest", "manifest.json", "sequence", "canvas", "annotation", "list", "range", "layer", "res" ]
+  let manifestShortId;
+
+  const iiifUriArr = iiifUri.split("/");
+
+  // if it follows the IIIF recommended URI patterns
+  for (let i=0; i < keywords.length; i++) {
+    if (iiifUriArr.includes(keywords[i])) {
+      manifestShortId = iiifUriArr.at(iiifUriArr.indexOf(keywords[i]) - 1);
+      break;
+    }
+  }
+  // fallback if no manifestShortId was found: return a string representation of the URI's hash.
+  manifestShortId = manifestShortId || getHash(iiifUri);
+  return manifestShortId;
+}
+
+/**
+ * extract the ID of a canvas from a canvas' URI.
+ * NOTE this only really works if `canvasUri` follows IIIF URI patterns.
+ * @param {string} canvasUri
+ * @returns {string}
+ */
+const getCanvasShortId = (canvasUri) =>
+  // IIIF compliant
+  canvasUri.includes("/canvas/")
+    ? canvasUri.split("/").at(-1).replace(".json", "")
+    : getHash(canvasUri);
+
+/**
+ * get the `on` of an annotation.
+ * reimplemented from SAS: https://github.com/glenrobson/SimpleAnnotationServer/blob/dc7c8c6de9f4693c678643db2a996a49eebfcbb0/src/main/java/uk/org/llgc/annotation/store/AnnotationUtils.java#L147
+ * @param {object} annotation
+ * @returns {string[]}
+ */
+const getAnnotationTarget = (annotation) => {
+  /** annotation.on is converted to an array of targets => extract the target for each item of the array */
+  const getSingleAnnotationTarget = (_target) => {
+    let _targetOut;
+
+    if (typeof(_target) === "string") {
+      // remove the fragment if necesary to get the full Canvas Id
+      const hashIdx = _target.indexOf("#");
+      _targetOut = hashIdx === -1
+        ? _target
+        : _target.substring(0, hashIdx);
+
+    } else {
+      // it's a SpecificResource => get the full image's id.
+      _targetOut = _target["full"];
+    }
+    if (isNullish(_targetOut)) {
+      throw new Error(`${getAnnotationTarget.name}: 'annotation.on' is not a valid IIIF 2.1 annotation target (with annotation=${_target})`)
+    }
+    return _targetOut;
+  }
+
+  return maybeToArray(annotation.on).map(getSingleAnnotationTarget);
+}
+
+/**
+ * @example "127.0.0.1:3000/data/2/wit9_man11_anno165/annotation/c26_abda6e3c-2926-4495-9787-cb3f3588e47c"
+ * @param {string} manifestShortId
+ * @param {string} canvasId
+ * @returns {string}
+ */
+const toAiiinotateAnnotationUri = (manifestShortId, canvasId) =>
+  `${PUBLIC_URL}/data/${IIIF_PRESENTATION_2}/${manifestShortId}/annotation/${canvasId}_${uuid4()}`;
+
+/**
+ * @example "127.0.0.1:3000/data/2/wit9_man11_anno165/manifest.json"
+ * @param {string} manifestShortId
+ * @returns {string}
+ */
+const toAiiinotateManifestUri = (manifestShortId) =>
+  `${PUBLIC_URL}/data/${IIIF_PRESENTATION_2}/${manifestShortId}/manifest.json`;
+
+/**
+ * if `canvasUri` follows the recommended IIIF 2.1 recommended URI pattern, convert it to a JSON manifest URI.
+ * @param {string} canvasUri
+ * @returns {string} : the manifest URI
+ */
+const canvasUriToManifestUri = (canvasUri) =>
+  canvasUri.split("/").slice(0,-2).join("/") + "/manifest.json";
+
+/** @returns {number[]?} */
+const fragmentSelectorToXywh = (fragmentSelector) => {
+  // fragmentSelector is of format: `$rootUrl#xywh=number,number,number,number`
+  // => get the `number,number,number,number` part
+  const selectorValue = (fragmentSelector.value || "").split("xywh=");
+  const xywhString = selectorValue.length > 1 ? selectorValue[1] : ""
+  if (xywhString.length) {
+    return xywhString.split(",").map((x) => parseInt(x));
+  }
+  return
+}
+
+/** @returns {Promise<number[]?>} */
+const svgSelectorToXywh = (svgSelector) => {
+  try {
+    return svgStringToXywh(svgSelector.value);
+  } catch (err) {
+    logger.warn(`could not build bounding box from SvgSelector because of error: ${err.message}`);
+    return
+  }
+}
+
+/** @returns {Promise<number[]?>} */
+const choiceSelectorToXywh = async (choiceSelector) => {
+  let xywh;
+  for (const selector of [ choiceSelector.item, choiceSelector.default ]) {
+    xywh = await selectorToXywh(selector);
+    if (xywh?.length) {
+      break;
+    }
+  }
+  return xywh;
+}
+
+/** @returns {Promise<number[]?>} */
+const selectorToXywh = async (selector) => {
+  const mapper = [
+    [ "oa:Choice", choiceSelectorToXywh ],
+    [ "oa:SvgSelector", svgSelectorToXywh ],
+    [ "oa:FragmentSelector", fragmentSelectorToXywh ],
+    [ "Choice", choiceSelectorToXywh ],
+    [ "SvgSelector", svgSelectorToXywh ],
+    [ "FragmentSelector", fragmentSelectorToXywh ],
+  ]
+  let xywh;
+  for (const [ selectorName, func ] of mapper) {
+    if (selector["@type"] === selectorName) {
+      xywh = await func(selector);
+      if (Array.isArray(xywh) && xywh?.length) {
+        // ensure `xywh` contains only floats + round to upper integer.
+        xywh = xywhToInt(xywh);
+        break
+      }
+    }
+  }
+  return xywh
+}
+
+// NOTE: is this really useful ?
+const normalizeSelectorType = (selector) => {
+  // the received specificResource `selector` may have its type specified using the key `type`. correct it to `@type`.
+  if (
+    isObject(selector) && Object.keys(selector).includes("type")
+  ) {
+    selector["@type"] = selector.type;
+    delete selector.type;
+  }
+  return selector;
+}
+
+const stringToSpecificResource = (target) => {
+  let [ full, fragment ] = target.split("#");
+  return {
+    "@id": target,
+    "@type": "oa:SpecificResource",
+    full: full,
+    selector: {
+      "@type": "oa:FragmentSelector",
+      value: fragment
+    }
+  }
+}
+
+/**
+ * handle a single value of `annotation.on` (when annotation.on is an array).
+ * essentially, this function ensures the `target` is a `SpecificResource` and extracts useful fields.
+ * @returns {Promise<object>}
+ */
+const makeSingleTarget = async (target) => {
+  const err = new Error(`${makeSingleTarget.name}: could not make target for annotation: 'annotation.on' must be an URI, a SpecificResource or an array of SpecificResources. The key 'SpecificResource.full' MUST be defined.`, { info: target });
+
+  let specificResource;
+
+  // 1. convert to SpecificResource
+  if (typeof(target) === "string" && !isNullish(target)) {
+    specificResource = stringToSpecificResource(target);
+  } else if (isObject(target) && target["@type"] === "oa:SpecificResource" && !isNullish(target["full"])) {
+    specificResource = target;
+    specificResource.selector = normalizeSelectorType(specificResource.selector);
+
+  // if target is neither a string nor a SpecificResource, raise
+  } else {
+    throw err
+  }
+
+  // 2. extract relevant fields
+  // extract xywh coordinates and return them as [x:int, y:int, w:int, h:int]
+  // NOTE: xywh extraxction is only supported for FragmentSelector and SvgSelector (or an oa:Choice containing either).
+  specificResource.xywh = await selectorToXywh(specificResource.selector);
+  specificResource.manifestUri = canvasUriToManifestUri(specificResource.full);
+  specificResource.manifestShortId = getManifestShortId(specificResource.full);
+
+  return specificResource
+}
+
+/**
+ * convert the annotation's `on` to a SpecificResource
+ * reimplemented from SAS: https://github.com/glenrobson/SimpleAnnotationServer/blob/dc7c8c6de9f4693c678643db2a996a49eebfcbb0/src/main/java/uk/org/llgc/annotation/store/AnnotationUtils.java#L123-L135
+ * @param {object} annotation
+ * @returns {Promise<object[]>} - the array of targets extracted from 'annotation.on'
+ */
+const makeTarget = async (annotation) => {
+  return await Promise.all(
+    maybeToArray(annotation.on).map(async (target) => await makeSingleTarget(target))
+  );
+}
+
+/**
+ * generate the annotation's ID from its `@id` key (if defined)
+ * reimplementated from SAS: https://github.com/glenrobson/SimpleAnnotationServer/blob/dc7c8c6de9f4693c678643db2a996a49eebfcbb0/src/main/java/uk/org/llgc/annotation/store/AnnotationUtils.java#L90-L97
+ * NOTE this should never fail, but results will only be reliable if the `annotation.on` follows the IIIF 2.1 canvas URI scheme
+ */
+const makeAnnotationId = (annotation, manifestShortId) => {
+  // we consider that all targets point to the same canvas and manifest => extract canvas and manifest info from the 1st target.
+  const targetArray = getAnnotationTarget(annotation);
+  if (targetArray.length < 1) {
+    throw new Error(`${makeAnnotationId.name}: could not extract target from annotation`)
+  }
+  const
+    firstTarget = targetArray[0],
+    canvasId = getCanvasShortId(firstTarget);
+  // if manifestShortId hasn't aldready been extracted, re-extract it
+  manifestShortId = manifestShortId || getManifestShortId(firstTarget);
+
+  if (isNullish(manifestShortId) || isNullish(canvasId)) {
+    throw new Error(`${makeAnnotationId.name}: could not make an 'annotationId' (with manifestShortId=${manifestShortId}, annotation=${annotation})`)
+  }
+
+  return toAiiinotateAnnotationUri(manifestShortId, canvasId);
+}
+
+/**
+ * NOTE: for pagination to work, we assume some things about the anatomy of the route that uses `toAnnotationList`:
+ * - `annotationListId` must be the URL used to fetch annotations and generate the annotationList
+ * - the URL must have a `page` query parameter that handles pagination
+ *
+ * params:
+ * - resources: the annotatons
+ * - annotationListId: the AnnotationList's '@id' key
+ * - label: optional description
+ * - hasNext: there is a next page (for paginated results)
+ * - page: page number (for paginated results)
+ *
+ * @param {{
+ *  resources: object[],
+ *  annotationListId: string,
+*   page: number,
+*   hasNext: boolean,
+ *  label: string?
+ * }}
+ * @returns {object} - the annotationList
+ */
+const toAnnotationList = ({
+  resources,
+  annotationListId,
+  page,
+  hasNext,
+  label
+}) => {
+  if (isNullish(annotationListId)) {
+    throw new Error("toAnnotationList: 'annotationListId' must be defined");
+  }
+
+  const annotationList = {
+    ...IIIF_PRESENTATION_2_CONTEXT,
+    "@type": "sc:AnnotationList",
+    "@id": annotationListId || "",  // NOTE: MUST be defined according to IIIF presentation API (but not always defined in SAS)
+    resources: resources
+  }
+  if (label) {
+    annotationList.label = label
+  }
+  if (page) {
+    const annotationListUrl = new URL(annotationListId);
+    if (page > 1) {
+      annotationListUrl.searchParams.set("page", page-1);
+      annotationList.prev = annotationListUrl.href;
+    }
+    if (hasNext) {
+      annotationListUrl.searchParams.set("page", page+1);
+      annotationList.next = annotationListUrl.href;
+    }
+  }
+  return annotationList;
+}
+
+export {
+  makeTarget,
+  makeAnnotationId,
+  toAiiinotateAnnotationUri,
+  toAiiinotateManifestUri,
+  toAnnotationList,
+  getManifestShortId,
+  getCanvasShortId,
+  getAnnotationTarget,
+  canvasUriToManifestUri,
+}

package/src/utils/iiif2Utils.test.js

@@ -0,0 +1,146 @@
+import test from "node:test";
+
+import { v4 as uuid4 } from "uuid";
+
+import build from "#src/app.js";
+import { getManifestShortId, getCanvasShortId, getAnnotationTarget, makeTarget, makeAnnotationId, toAnnotationList } from "#utils/iiif2Utils.js";
+import { objectHasKey, visibleLog } from "#utils/utils.js";
+import { PUBLIC_URL } from "#constants";
+
+// hash-validating regex
+const hashRgx = /^\d+$/;
+
+test("test 'iiif2Utils' functions", async (t) => {
+  const
+    fastify = await build("test"),
+    { annotations2Valid, annotations2Invalid } = fastify.fixtures;
+
+  await fastify.ready();
+
+  t.after(() => fastify.close());
+
+  t.test("test 'getManifestShortId'", (t) => {
+    const
+      s1 = `manifest_${uuid4()}`,
+      s2 = `extra_${uuid4()}`,
+      // urls for which the function will manage to extract `s1`
+      urlOk = [
+        `http://www.example.com/examplePrefix/${s1}/manifest`,
+        `http://www.example.com/examplePrefix/${s1}/manifest.json`,
+        `http://www.example.com/examplePrefix/${s1}/sequence/${s2}`,
+        `http://www.example.com/examplePrefix/${s1}/canvas/${s2}`,
+        `http://www.example.com/examplePrefix/${s1}/annotation/${s2}`,
+        `http://www.example.com/examplePrefix/${s1}/list/${s2}`,
+        `http://www.example.com/examplePrefix/${s1}/range/${s2}`,
+        `http://www.example.com/examplePrefix/${s1}/layer/${s2}`,
+        `http://www.example.com/examplePrefix/${s1}/res/${s2}.png`,
+      ],
+      // urls for which `s1` won't be returned, and instead a hash will be returned
+      urlHash = [
+        `http://example.com/example/collection/${s2}`,
+        `http://example.com/${s1}`
+      ];
+
+    urlOk.map((url) =>
+      t.assert.strictEqual(getManifestShortId(url), s1));
+    urlHash.map((url) =>
+      t.assert.strictEqual(hashRgx.test(getManifestShortId(url)), true));
+  })
+
+  t.test("test 'getCanvasShortId'", (t) => {
+    const
+      s1 = `manifest_${uuid4()}`,
+      s2 = `canvas_${uuid4()}`,
+      urlOk = [
+        `http://www.example.com/examplePrefix/${s1}/canvas/${s2}`,
+        `http://www.example.com/examplePrefix/${s1}/canvas/${s2}.json`,
+
+      ],
+      urlHash = [
+        `http://example.com/example/${s2}`,
+        `http://example.com/${s2}`
+      ]
+    urlOk.map((url) =>
+      t.assert.strictEqual(getCanvasShortId(url), s2));
+    urlHash.map((url) =>
+      t.assert.strictEqual(hashRgx.test(getCanvasShortId(url)), true));
+
+  })
+
+  await t.test("test 'makeTarget'", async (t) => {
+    await Promise.all(
+      annotations2Valid.map(async (annotation) =>
+        // `rejects` / `doesNotReject` works for aync functions,
+        // contrary to `throws` / `doesNotThrow`
+        // https://stackoverflow.com/a/35782749
+        t.assert.doesNotReject(async () => await makeTarget(annotation))
+      )
+    );
+    await Promise.all(
+      annotations2Invalid.map(async (annotation) =>
+        t.assert.rejects(async () => await makeTarget(annotation))
+      )
+    );
+  })
+
+  await t.test("test 'getAnnotationTarget'", (t) => {
+    annotations2Valid.map((annotation) =>
+      t.assert.doesNotThrow(() => getAnnotationTarget(annotation))
+    );
+    annotations2Invalid.map((annotation) =>
+      t.assert.throws(() => getAnnotationTarget(annotation), Error)
+    )
+  })
+
+  await t.test("test 'makeAnnotationId'", (t) => {
+    // https://stackoverflow.com/a/6969486
+    const escapeRegExp = (string) =>
+      string.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); // $& means the whole matched string
+
+    const rgx = new RegExp(`^${escapeRegExp(PUBLIC_URL)}/data/2/[^(\\s|/)]+/annotation/[^\\.]+$`);
+    annotations2Valid.map((annotation) =>
+      t.assert.strictEqual(rgx.test(makeAnnotationId(annotation)), true));
+    annotations2Invalid.map((annotation) =>
+      t.assert.throws(() => makeAnnotationId(annotation)));
+  })
+
+  await t.test("test 'toAnnotationList'", (t) => {
+    /**
+     * @param {"prev"|"next"} val
+     * @returns {(_annotationList: object) => string?} */
+    const getPage = (val) => {
+      if (![ "prev", "next" ].includes(val)) {
+        throw new Error(`'getPage': invalid value for 'val': '${val}'`);
+      }
+      return (_annotationList) => {
+        if (objectHasKey(annotationList, val)) {
+          return new URL(annotationList[val]).searchParams.get("page")
+        }
+        return undefined;
+      }
+    }
+    const getPagePrev = getPage("prev");
+    const getPageNext = getPage("next");
+
+    const testUrl = new URL(`http://www.example.com/prefix/manifest-${uuid4()}/list/anno-list-${uuid4()}`);
+    const data = [
+      { page: 3, hasNext: true, prevNum: "2", nextNum: "4" },
+      { page: 1, hasNext: true, prevNum: undefined, nextNum: "2" },
+      { page: 1, hasNext: false, prevNum: undefined, nextNum: undefined },
+    ];
+    let annotationList;
+
+    for (const { page, hasNext, prevNum, nextNum } of data) {
+      annotationList = toAnnotationList({
+        resources: [],
+        annotationListId: testUrl.href,
+        page: page,
+        hasNext: hasNext,
+      });
+      t.assert.deepStrictEqual(getPagePrev(annotationList)==prevNum, true);
+      t.assert.deepStrictEqual(getPageNext(annotationList)==nextNum, true);
+    }
+
+  })
+
+})

package/src/utils/iiifUtils.js

@@ -0,0 +1,18 @@
+import { getHash } from "#utils/utils.js";
+
+const IIIF_PRESENTATION_2 = 2;
+const IIIF_PRESENTATION_3 = 3;
+const IIIF_SEARCH_1 = 1;
+const IIIF_SEARCH_2 = 2;
+const IIIF_PRESENTATION_2_CONTEXT = { "@context": "http://iiif.io/api/presentation/2/context.json" };
+const IIIF_PRESENTATION_3_CONTEXT = { "@context": "http://iiif.io/api/presentation/3/context.json" };
+
+
+export {
+  IIIF_PRESENTATION_2,
+  IIIF_PRESENTATION_3,
+  IIIF_SEARCH_1,
+  IIIF_SEARCH_2,
+  IIIF_PRESENTATION_2_CONTEXT,
+  IIIF_PRESENTATION_3_CONTEXT,
+}

package/src/utils/logger.js

@@ -0,0 +1,119 @@
+import path from "path";
+import fs from "fs";
+
+import pino from "pino";
+
+import { LOG_TARGET, LOG_DIR, LOG_LEVEL } from "#constants";
+
+// a LOG_DIR is defined and it doesn't exist
+if (LOG_DIR?.length && !fs.existsSync(LOG_DIR)) {
+  fs.mkdirSync(LOG_DIR, { recursive: true });
+}
+
+const stdoutLogTarget = {
+  level: "debug",
+  target: "pino-pretty",
+  options: {
+    colorize: true,
+    singleLine: false,
+    translateTime: "SYS:standard",
+  },
+}
+const fileLogTargets = [
+  {
+    level: "debug",
+    target: "pino/file",
+    options: { destination: path.join(LOG_DIR, "aiiinotate_debug.log") },
+  },
+  {
+    level: "error",
+    target: "pino/file",
+    options: { destination: path.join(LOG_DIR, "aiiinotate_error.log") },
+  },
+]
+
+const makePinoLogger = () => {
+  // disable logging entierly
+  if (LOG_TARGET==="off") {
+    return pino({ enabled: false });
+  }
+
+  // otherwise, generate a specific logger based on the value of "LOG_TARGET"
+  const logTarget = {
+    stdout: [ stdoutLogTarget ],
+    file: [ ...fileLogTargets ],
+    "stdout+file": [ stdoutLogTarget, ...fileLogTargets ]
+  }[LOG_TARGET];
+
+  return pino({
+    level: LOG_LEVEL,
+    transport: {
+      targets: logTarget,
+    },
+    serializers: {
+      req: (req) => ({
+        id: req.id,
+        method: req.method,
+        url: req.url,
+      }),
+      res: (res) => ({
+        statusCode: res.statusCode,
+      }),
+    }
+  })
+}
+
+// Wrapper for caller information
+class Logger {
+  constructor() {
+    this.pinoLogger = makePinoLogger();
+  }
+
+  _getCaller() {
+    const stack = new Error().stack.split("\n");
+    const callerLine = stack[3]; // Skip Error, _getCaller, and the actual method
+    const match = callerLine.match(/at (.+) \((.+):(\d+):(\d+)\)/);
+
+    if (match) {
+      return {
+        funcName: match[1],
+        module: path.basename(match[2], path.extname(match[2])),
+        lineno: parseInt(match[3]),
+      };
+    }
+
+    return { funcName: "unknown", module: "unknown", lineno: null };
+  }
+
+  debug(message, meta = {}) {
+    const caller = this._getCaller();
+    this.pinoLogger.debug({ ...caller, ...meta }, message);
+  }
+
+  info(message, meta = {}) {
+    const caller = this._getCaller();
+    this.pinoLogger.info({ ...caller, ...meta }, message);
+  }
+
+  warn(message, meta = {}) {
+    const caller = this._getCaller();
+    this.pinoLogger.warn({ ...caller, ...meta }, message);
+  }
+
+  error(message, meta = {}) {
+    const caller = this._getCaller();
+    this.pinoLogger.error({ ...caller, ...meta }, message);
+  }
+
+  child(bindings) {
+    return this.pinoLogger.child(bindings);
+  }
+
+  setLevel(level) {
+    this.pinoLogger.level = level;
+  }
+}
+
+const logger = new Logger()
+
+export default logger;