aiiinotate 0.2.0

package/src/data/manifests/routes.js

@@ -0,0 +1,95 @@
+import fastifyPlugin from "fastify-plugin";
+
+import { makeResponsePostSchema, returnError, makeResponseSchema } from "#utils/routeUtils.js";
+import { objectHasKey, getFirstNonEmptyPair, visibleLog } from "#utils/utils.js";
+
+/** @typedef {import("#types").FastifyInstanceType} FastifyInstanceType */
+/** @typedef {import("#types").Manifests2InstanceType} Manifests2InstanceType */
+/** @typedef {import("#types").Manifests3InstanceType} Manifests3InstanceType */
+
+/**
+ * @param {FastifyInstanceType} fastify
+ * @param {object} options
+ * @param {Function} done
+ */
+function manifestsRoutes(fastify, options, done) {
+  const
+    /** @type {Manifests2InstanceType} */
+    manifests2 = fastify.manifests2,
+    /** @type {Manifests3InstanceType} */
+    manifests3 = fastify.manifests3,
+    iiifPresentationVersionSchema = fastify.schemasBase.getSchema("presentation"),
+    responsePostSchema = makeResponsePostSchema(fastify),
+    collectionSchema = makeResponseSchema(fastify, fastify.schemasPresentation2.getSchema("collection"));
+
+  ///////////////////////////////////////////////
+  // read routes
+
+  fastify.get(
+    "/manifests/:iiifPresentationVersion",
+    {
+      schema: {
+        params: {
+          type: "object",
+          properties: {
+            iiifPresentationVersion: iiifPresentationVersionSchema
+          }
+        },
+        response: collectionSchema,
+      }
+    },
+    async (request, reply) => {
+      const { iiifPresentationVersion } = request.params;
+      try {
+        return iiifPresentationVersion === 2
+          ? await manifests2.getManifests()
+          : manifests3.notImplementedError();
+      } catch (err) {
+        returnError(request, reply, err);
+      }
+    }
+  )
+
+  ///////////////////////////////////////////////
+  // insert routes
+
+  fastify.post(
+    "/manifests/:iiifPresentationVersion/create",
+    {
+      schema: {
+        params: {
+          type: "object",
+          properties: {
+            iiifPresentationVersion: iiifPresentationVersionSchema
+          }
+        },
+        body: { $ref: fastify.schemasRoutes.getSchema("manifest2Or3") },
+        response: responsePostSchema
+      }
+    },
+    async (request, reply) => {
+      const
+        { iiifPresentationVersion } = request.params,
+        manifestData = request.body;
+      try {
+        if ( objectHasKey(manifestData, "uri") ) {
+          return iiifPresentationVersion === 2
+            ? await manifests2.insertManifestFromUri(manifestData.uri)
+            : manifests3.notImplementedError();
+        } else {
+          // visibleLog(await manifests2.insertManifest(manifestData));
+          return iiifPresentationVersion === 2
+            ? await manifests2.insertManifest(manifestData)
+            : manifests3.notImplementedError();
+        }
+      } catch (err) {
+        returnError(request, reply, err, request.body);
+      }
+    }
+  );
+
+  done();
+}
+
+export default fastifyPlugin(manifestsRoutes);
+

package/src/data/manifests/routes.test.js

@@ -0,0 +1,69 @@
+import test from "node:test";
+
+import build from "#src/app.js";
+import { visibleLog } from "#utils/utils.js";
+import { getManifestShortId } from "#utils/iiif2Utils.js";
+import { testPostRouteCurry, injectPost, injectTestManifest, assertStatusCode, assertObjectKeys} from "#utils/testUtils.js";
+
+/** @typedef {import("#types").FastifyInstanceType} FastifyInstanceType */
+/** @typedef {import("#types").NodeTestType} NodeTestType */
+
+test("test manifests Routes", async (t) => {
+  const
+    fastify = await build("test"),
+    testPostRoute = testPostRouteCurry(fastify),
+    testPostRouteCreate = testPostRoute("insert"),
+    testPostRouteCreateSuccess = testPostRouteCreate(true),
+    testPostRouteCreateFailure = testPostRouteCreate(false),
+    {
+      manifest2Valid,
+      manifest2Invalid,
+      manifest2ValidUri,
+      manifest2InvalidUri,
+    } = fastify.fileServer;
+
+  await fastify.ready();
+  // close the app after running the tests
+  t.after(async () => await fastify.close());
+  // after each subtest has run, delete all database records
+  t.afterEach(async() => fastify.emptyCollections());
+
+  // NOTE: it is necessary to run the app because internally there are fetches to external data.
+  try {
+    await fastify.listen({ port: process.env.APP_PORT });
+  } catch (err) {
+    console.log("FASTIFY ERROR", err);
+    throw err;
+  }
+
+  await t.test("test route /manifests/:iiifPresentationVersion/create", async (t) => {
+    const data = [
+      [ [manifest2Valid, manifest2ValidUri], testPostRouteCreateSuccess ],
+      [ [manifest2Invalid, manifest2InvalidUri], testPostRouteCreateFailure ]
+    ];
+    for ( let i=0; i<data.length; i++ ) {
+      const [ testData, func ] = data.at(i);
+      for ( let j=0; j<testData.length; j++ ) {
+        const payload = testData.at(j);
+        await func(t, "/manifests/2/create", payload);
+        // for some reason, it is necessary to call `emptyCollections` explicitly here to avoid a JSONSchema validation error.
+        await fastify.emptyCollections();
+      }
+    }
+  })
+
+  await t.test("test route /manifests/:iiifPresentationVersion/collection", async (t) => {
+    await injectTestManifest(fastify, t, manifest2Valid);
+    const r = await fastify.inject({
+      method: "GET",
+      url: "/manifests/2"
+    });
+    assertStatusCode(t, r, 200);
+    assertObjectKeys(
+      t,
+      JSON.parse(r.body),
+      [ "@context", "@id", "@type", "members", "label" ]
+    );
+  })
+
+})

package/src/data/routes.js

@@ -0,0 +1,141 @@
+import fastifyPlugin from "fastify-plugin"
+
+import { pathToUrl, ajvCompile, inspectObj, getFirstNonEmptyPair } from "#utils/utils.js";
+import { returnError, makeResponsePostSchema } from "#utils/routeUtils.js";
+
+/** @typedef {import("#types").Manifests2InstanceType} Manifests2InstanceType */
+/** @typedef {import("#types").Manifests3InstanceType} Manifests3InstanceType */
+/** @typedef {import("#types").Annotations2InstanceType} Annotations2InstanceType */
+/** @typedef {import("#types").Annotations3InstanceType} Annotations3InstanceType */
+
+/**
+ * @param {FastifyInstanceType} fastify
+ * @param {object} options
+ * @param {Function} done
+ */
+function commonRoutes(fastify, options, done) {
+  const
+    /** @type {Annotations2InstanceType} */
+    annotations2 = fastify.annotations2,
+    /** @type {Annotations3InstanceType} */
+    annotations3 = fastify.annotations3,
+    /** @type {Manifests2InstanceType} */
+    manifests2 = fastify.manifests2,
+    /** @type {Manifests3InstanceType} */
+    manifests3 = fastify.manifests3,
+    iiifPresentationVersionSchema = fastify.schemasBase.getSchema("presentation"),
+    iiifSearchApiVersionSchema = fastify.schemasBase.getSchema("search"),
+    iiifAnnotationListSchema = fastify.schemasPresentation2.getSchema("annotationList"),
+    routeDeleteSchema = fastify.schemasRoutes.getSchema("routeDelete"),
+    responsePostSchema = makeResponsePostSchema(fastify),
+    validatorRouteAnnotationDeleteSchema = ajvCompile(fastify.schemasResolver(
+      fastify.schemasRoutes.getSchema("routeAnnotationDelete")
+    )),
+    validatorRouteManifestDeleteSchema = ajvCompile(fastify.schemasResolver(
+      fastify.schemasRoutes.getSchema("routeManifestDelete")
+    ));
+
+  fastify.get(
+    "/search-api/:iiifSearchVersion/manifests/:manifestShortId/search",
+    {
+      schema: {
+        params: {
+          type: "object",
+          properties: {
+            iiifSearchVersion: iiifSearchApiVersionSchema,
+            manifestShortId: { type: "string" },
+          },
+        },
+        querystring: {
+          type: "object",
+          properties: {
+            q: { type: "string" },
+            motivation: {
+              type: "string",
+              enum: ["painting", "non-painting", "commenting", "describing", "tagging", "linking"]
+            }
+          }
+        },
+        response: {
+          200: iiifAnnotationListSchema
+        }
+      }
+    },
+    async (request, reply) => {
+      const
+        queryUrl = pathToUrl(request.url),
+        { iiifSearchVersion, manifestShortId } = request.params,
+        { q, motivation } = request.query;
+
+      if ( iiifSearchVersion===1 ) {
+        return await annotations2.search(queryUrl, manifestShortId, q, motivation);
+      } else {
+        annotations3.notImplementedError();
+      }
+    }
+  );
+
+  /////////////////////////////////////////////
+  // DELETE routes
+
+  /**
+   * manifest and annotations work in the same manner, so we group them here.
+   * we add a custom `preHandler` to ensure that `queryString` follows the proper schema.
+   */
+  fastify.delete(
+    "/:collectionName/:iiifPresentationVersion/delete",
+    {
+      schema: {
+        params: {
+          type: "object",
+          properties: {
+            collectionName: { type: "string", enum: [ "annotations", "manifests" ] },
+            iiifPresentationVersion: iiifPresentationVersionSchema
+          }
+        },
+        queryString: routeDeleteSchema,
+        response: responsePostSchema,
+      },
+      preValidation: async (request, reply) => {
+        // implement a custom validation hook: depending on the value of `collectionName`, run different schema validations.
+        const
+          { collectionName } = request.params,
+          query = request.query,
+          validator =
+            collectionName==="annotations"
+              ? validatorRouteAnnotationDeleteSchema
+              : validatorRouteManifestDeleteSchema,
+          error = new Error(`Error validating DELETE route on collection '${collectionName}' with queryString '${inspectObj(query)}'`);
+
+        if ( !validator(query) ) {
+          returnError(request, reply, error, {}, 400);
+        }
+        return;
+      }
+    },
+    async (request, reply) => {
+      const
+        { collectionName, iiifPresentationVersion } = request.params,
+        [ deleteKey, deleteVal ] = getFirstNonEmptyPair(request.query);
+
+      try {
+        if ( collectionName==="annotations" ) {
+          return iiifPresentationVersion === 2
+            ? await annotations2.deleteAnnotations(deleteKey, deleteVal)
+            : annotations3.notImplementedError();
+        } else {
+          return iiifPresentationVersion === 2
+            ? await manifests2.deleteManifest(deleteKey, deleteVal)
+            : manifests3.notImplementedError();
+        }
+      } catch (err) {
+        returnError(request, reply, err, request.body);
+      }
+
+    }
+  )
+
+  done();
+}
+
+export default fastifyPlugin(commonRoutes);

package/src/data/routes.test.js

@@ -0,0 +1,117 @@
+import test from "node:test";
+
+import { v4 as uuid4 } from "uuid";
+
+import build from "#src/app.js";
+import { getRandomItem } from "#utils/utils.js";
+import { getManifestShortId } from "#utils/iiif2Utils.js";
+import { testPostRouteCurry, testDeleteRouteCurry, injectPost, injectTestManifest, injectTestAnnotations, assertErrorValidResponse, assertDeleteValidResponse } from "#utils/testUtils.js";
+
+/** @typedef {import("#types").FastifyInstanceType} FastifyInstanceType */
+/** @typedef {import("#types").NodeTestType} NodeTestType */
+
+test("test common routes", async (t) => {
+  const
+    /** @type {FastifyInstanceType} */
+    fastify = await build("test"),
+    testPostRoute = testPostRouteCurry(fastify),
+    testDeleteRoute = testDeleteRouteCurry(fastify),
+    { manifest2Valid, annotationList } = fastify.fileServer;
+
+  await fastify.ready();
+  // close the app after running the tests
+  t.after(async () => await fastify.close());
+  // after each subtest has run, delete all database records
+  t.afterEach(async () => fastify.emptyCollections());
+
+  // NOTE: it is necessary to run the app because internally there are fetches to external data.
+  try {
+    await fastify.listen({ port: process.env.APP_PORT });
+  } catch (err) {
+    console.log("FASTIFY ERROR", err);
+    throw err;
+  }
+
+  ////////////////////////////////////////////////
+  // DELETE routes
+
+  await t.test("test route /:collectionName/:iiifPresentationVersion/delete", async (t) => {
+
+    await t.test("test preValidation hook for queryString validation", async (t) => {
+      const data = [
+        ["/manifests/2/delete?canvasUri=xxx", false],    // canvasUri is only allowed if `collectionName==="annotations"` => will fail.
+        ["/manifests/2/delete?manifestShortId=xxx", true]
+      ];
+      for ( let i=0; i<data.length; i++ ) {
+        const [url, expectSuccess] = data.at(i);
+        const r = await fastify.inject({
+          method: "DELETE",
+          url: url
+        })
+        expectSuccess
+          ? assertDeleteValidResponse(t, r)
+          : assertErrorValidResponse(t, r, 400);
+      }
+    });
+
+    await t.test("test route /manifests/:iiifPresentationVersion/delete", async (t) => {
+      const
+        manifest = manifest2Valid,
+        deleteQuery = [
+          [ "uri", manifest["@id"] ],
+          [ "manifestShortId", getManifestShortId(manifest["@id"]) ]
+        ];
+
+      for ( let i=0; i<deleteQuery.length; i++ ) {
+        const [deleteBy, deleteKey] = deleteQuery.at(i);
+        await injectTestManifest(fastify, t, manifest);
+        await testDeleteRoute(t, `/manifests/2/delete?${deleteBy}=${deleteKey}`, 1);
+        await fastify.emptyCollections();
+      }
+    });
+
+    await t.test("test route /annotations/:iiifPresentationVersion/delete", async (t) => {
+      const deletePipeline = async (validFilter) =>
+        // validFilter is true => delete data that exists in the db (test that deletions are done correctly),
+        // validFilter is false => delete data that doesn't exist (test that nothing is deleted by accident)
+        await Promise.all(
+          // all 3 possible ways to delete data
+          ["manifestShortId", "canvasUri", "uri"].map(
+            async (deleteBy) =>
+              await t.test(`validFilter: ${validFilter}, deleteBy: ${deleteBy}`, async (t) => {
+
+                await injectTestAnnotations(fastify, t, annotationList);
+                const
+                  annotations = await fastify.mongo.db.collection("annotations2").find({}).toArray(),
+                  deleteKey =
+                    validFilter
+                      ? deleteBy==="uri"
+                        ? getRandomItem(annotations.map((a) => a["@id"]))
+                        : deleteBy==="canvasUri"
+                          ? getRandomItem(annotations.map((a) => a.on.full))
+                          : getRandomItem(annotations.map((a) => a.on.manifestShortId))
+                      : `invalid-filter-${uuid4()}`,
+                  expectedDeletedCount =
+                    validFilter
+                      ? deleteBy==="uri"
+                        ? annotations.filter((a) => a["@id"]===deleteKey).length
+                        : deleteBy==="canvasUri"
+                          ? annotations.filter((a) => a.on.full===deleteKey).length
+                          : annotations.filter((a) => a.on.manifestShortId===deleteKey).length
+                      : 0;
+
+                await testDeleteRoute(t, `/annotations/2/delete?${deleteBy}=${deleteKey}`, expectedDeletedCount);
+              })
+          )
+        );
+
+      await deletePipeline(true);
+      await deletePipeline(false);
+    });
+
+  })
+
+
+  return;
+})
+

package/src/data/utils/iiif2Utils.js

@@ -0,0 +1,196 @@
+import { v4 as uuid4 } from "uuid";
+
+import { maybeToArray, getHash, isNullish, isObject } from "#utils/utils.js";
+import { IIIF_PRESENTATION_2, IIIF_PRESENTATION_2_CONTEXT } from "#utils/iiifUtils.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) => {
+  const target = annotation.on;  // either string or SpecificResource
+  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;
+}
+
+/**
+ * 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
+ */
+const makeTarget = (annotation) => {
+  const
+    // must be either string or SpecificResource
+    target = annotation.on,
+    // error that will raise is `target` can't be processed
+    err = new Error(`${makeTarget.name}: could not make target for annotation: 'annotation.on' must be an URI or an object with 'annotation.on.@type==="oa:SpecificResource"' and 'annotation.on.@id' must be a string URI`, { info: annotation });
+
+  let specificResource;
+
+  // convert to SpecificResource if it's not aldready the case
+  if ( typeof(target) === "string" && !isNullish(target) ) {
+    let [full, fragment] = target.split("#");
+    specificResource = {
+      "@type": "oa:SpecificResource",
+      full: full,
+      selector: {
+        "@type": "oa:FragmentSelector",
+        value: fragment
+      }
+    }
+  } else if ( isObject(target) ) {
+    // if 'target' is an object but not a specificresource, raise.
+    if ( target["@type"] === "oa:SpecificResource" && !isNullish(target["full"]) ) {
+      specificResource = target;
+      // the received specificResource `selector` may have its type specified using the key `type`. correct it to `@type`.
+      if ( isObject(target.selector) && Object.keys(target.selector).includes("type") ) {
+        target.selector["@type"] = target.selector.type;
+        delete target.selector.type;
+      }
+    } else {
+      throw err
+    }
+  } else {
+    throw err
+  }
+
+  return specificResource
+}
+
+/**
+ * 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) => {
+  const
+    target = getAnnotationTarget(annotation),
+    canvasId = getCanvasShortId(target);
+  // if manifestShortId hasn't aldready been extracted, re-extract it
+  manifestShortId = manifestShortId || getManifestShortId(target);
+
+  if ( isNullish(manifestShortId) || isNullish(canvasId) ) {
+    throw new Error(`${makeAnnotationId.name}: could not make an 'annotationId' (with manifestShortId=${manifestShortId}, annotation=${annotation})`)
+  }
+
+  return annotationUri(manifestShortId, canvasId);
+}
+
+/**
+ * @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 annotationUri = (manifestShortId, canvasId) =>
+  `${process.env.APP_BASE_URL}/data/${IIIF_PRESENTATION_2}/${manifestShortId}/annotation/${canvasId}_${uuid4()}`;
+
+const manifestUri = (manifestShortId) =>
+  `${process.env.APP_BASE_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";
+
+/**
+ *
+ * @param {object[]} resources: the annotatons
+ * @param {string?} annotationListId: the AnnotationList's '@id' key
+ * @param {string?} label: optional description
+ * @returns {object}
+ */
+const toAnnotationList = (resources, annotationListId, label) => {
+  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
+  }
+  return annotationList;
+}
+
+export {
+  makeTarget,
+  makeAnnotationId,
+  annotationUri,
+  manifestUri,
+  toAnnotationList,
+  getManifestShortId,
+  getCanvasShortId,
+  getAnnotationTarget,
+  canvasUriToManifestUri,
+}