aiiinotate 0.2.0

package/src/data/annotations/routes.js

@@ -0,0 +1,271 @@
+import fastifyPlugin from "fastify-plugin"
+
+import { pathToUrl, objectHasKey, maybeToArray, inspectObj, throwIfKeyUndefined, throwIfValueError, getFirstNonEmptyPair, visibleLog } from "#utils/utils.js";
+import { makeResponseSchema, makeResponsePostSchema, returnError } from "#utils/routeUtils.js";
+
+
+/** @typedef {import("#types").FastifyInstanceType} FastifyInstanceType */
+/** @typedef {import("#types").Annotations2InstanceType} Annotations2InstanceType */
+/** @typedef {import("#types").Annotations3InstanceType} Annotations3InstanceType */
+
+/**
+ * validate an annotation, annotationPage or annotationList: that is, ensure it fits the IIIF presentation API
+ * @param {2|3} iiifPresentationVersion
+ * @param {object} annotationData
+ * @param {boolean} isListOrPage: it's an annotationList or annotationPage instead of a regular annotation.
+ */
+const validateAnnotationVersion = (iiifPresentationVersion, annotationData, isListOrPage=false) => {
+  // object keys are always strings, so we need to convert to string (https://stackoverflow.com/questions/3633362)
+  iiifPresentationVersion = iiifPresentationVersion.toString();
+  const expectedTypeKeys = {
+    "2": "@type",
+    "3": "type"
+  };
+  throwIfKeyUndefined(expectedTypeKeys, iiifPresentationVersion);
+  const expectedTypeKey = expectedTypeKeys[iiifPresentationVersion];
+  throwIfKeyUndefined(annotationData, expectedTypeKey);
+  const expectedTypeVal = (
+    isListOrPage
+      ? { "2": "sc:AnnotationList", "3":"AnnotationPage"}
+      : { "2": "oa:Annotation", "3": "Annotation" }
+  )[iiifPresentationVersion];
+  throwIfValueError(annotationData, expectedTypeKey, expectedTypeVal);
+}
+
+/**
+ * `annotationArray` is an array of AnnotationLists or AnnotationPages, depending on the IIIF Presentaion API version.
+ * assert that it indeed the case, raise otherwise
+ * @param {2|3} iiifPresentationVersion
+ * @param {object[]} annotationArray
+ * @returns {void}
+ */
+const validateAnnotationArrayVersion = (iiifPresentationVersion, annotationArray) =>
+  annotationArray.map(annotationData => validateAnnotationVersion(iiifPresentationVersion, annotationData, true));
+
+/**
+ * @param {import("#types").InsertResponseArrayType} insertResponseArray
+ * @returns {import("#types").InsertResponseType}
+ */
+const reduceInsertResponseArray = (insertResponseArray) => ({
+  insertedCount: insertResponseArray.reduce((acc, r) => acc+r.insertedCount, 0),
+  insertedIds: insertResponseArray.reduce((acc, r) => acc.concat(r.insertedIds), [])
+})
+
+
+/**
+ * Encapsulates the routes
+ * @param {FastifyInstanceType} fastify  Encapsulated Fastify Instance
+ * @param {object} options plugin options, refer to https://fastify.dev/docs/latest/Reference/Plugins/#plugin-options
+ * @param {Function} done
+ */
+function annotationsRoutes(fastify, options, done) {
+  const
+    /** @type {Annotations2InstanceType} */
+    annotations2 = fastify.annotations2,
+    /** @type {Annotations3InstanceType} */
+    annotations3 = fastify.annotations3,
+    iiifPresentationVersionSchema = fastify.schemasBase.getSchema("presentation"),
+    routeAnnotationCreateManySchema = fastify.schemasRoutes.getSchema("routeAnnotationCreateMany"),
+    iiifAnnotationListSchema = fastify.schemasPresentation2.getSchema("annotationList"),
+    iiifAnnotation2ArraySchema = fastify.schemasPresentation2.getSchema("annotationArray"),
+    iiifAnnotation2Schema = fastify.schemasPresentation2.getSchema("annotation"),
+    responsePostSchema = makeResponsePostSchema(fastify);
+
+  /////////////////////////////////////////////////////////
+  // get routes
+
+  /** get all annotations by a canvas URI */
+  fastify.get(
+    "/annotations/:iiifPresentationVersion/search",
+    {
+      schema: {
+        params: {
+          type: "object",
+          properties: {
+            iiifPresentationVersion: iiifPresentationVersionSchema
+          }
+        },
+        querystring: {
+          type: "object",
+          properties: {
+            uri: { type: "string" },
+            asAnnotationList: { type: "boolean" },
+          }
+        },
+        response: makeResponseSchema(
+          fastify,
+          {
+            oneOf: [
+              fastify.schemasResolver(iiifAnnotationListSchema),
+              fastify.schemasResolver(iiifAnnotation2ArraySchema)
+            ]
+          },
+        )
+      },
+    },
+    async (request, reply) => {
+      const
+        queryUrl = pathToUrl(request.url),
+        { iiifPresentationVersion } = request.params,
+        { uri, asAnnotationList } = request.query;
+
+      try {
+        if (iiifPresentationVersion === 2) {
+          return await annotations2.findByCanvasUri(queryUrl, uri, asAnnotationList);
+        } else {
+          annotations3.notImplementedError();
+        }
+      } catch (err) {
+        returnError(request, reply, err);
+      }
+    }
+  );
+
+  /** retrieve a single annotation by its "@id"|"id". this route defers an annotation */
+  fastify.get(
+    "/data/:iiifPresentationVersion/:manifestShortId/annotation/:annotationShortId",
+    {
+      schema: {
+        params: {
+          type: "object",
+          properties: {
+            iiifPresentationVersion: iiifPresentationVersionSchema,
+            manifestShortId: { type: "string" },
+            annotationShortId: { type: "string" },
+          }
+        },
+        response: makeResponseSchema(
+          fastify,
+          fastify.schemasResolver(iiifAnnotation2Schema)
+        )
+      }
+    },
+    async (request, reply) => {
+      const
+        annotationUri = pathToUrl(request.url),
+        { iiifPresentationVersion} = request.params;
+      try {
+        return iiifPresentationVersion === 2
+          ? annotations2.findById(annotationUri)
+          : annotations3.notImplementedError();
+      } catch (err) {
+        returnError(request, reply, err);
+      }
+    }
+  )
+
+  /////////////////////////////////////////////////////////
+  // create/update routes
+
+  /** create or update a single annotation from an annotation object */
+  fastify.post(
+    "/annotations/:iiifPresentationVersion/:action",
+    {
+      schema: {
+        params: {
+          type: "object",
+          properties: {
+            iiifPresentationVersion: iiifPresentationVersionSchema,
+            action: { type: "string", enum: [ "create", "update" ] }
+          }
+        },
+        body: { type: "object" } /* routeAnnotations2Or3Schema */,
+        response: responsePostSchema
+      },
+    },
+    async (request, reply) => {
+      const
+        { iiifPresentationVersion, action } = request.params,
+        annotation = request.body;
+
+      try {
+        validateAnnotationVersion(iiifPresentationVersion, annotation);
+        // insert or update
+        if ( iiifPresentationVersion === 2 ) {
+          return action==="create"
+            ? await annotations2.insertAnnotation(annotation)
+            : await annotations2.updateAnnotation(annotation);
+        } else {
+          annotations3.notImplementedError();
+        }
+
+      } catch (err) {
+        returnError(request, reply, err, request.body);
+      }
+    }
+  )
+
+  /**
+   * create several annotations from:
+   * - an annotationList (if iiifPresentationVersion === 2)
+   * - an annotationPage (if iiifPresentationVersion === 3)
+   * - an URI to an annotationList or annotationPage
+   * - or an Array of any of the previous
+   *
+   * NOTE that POST body size is limited to 1MB, so your query might be rejected. body size is limited by:
+   * - fastify's `bodyLimit` (https://fastify.dev/docs/latest/Reference/Server/#bodylimit)
+   * - nginx's `client_max_body_size` (https://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size)
+   * - any other server's max body size.
+   * both fastify and nginx limit body size defaults to to 1MB.
+   */
+  fastify.post(
+    "/annotations/:iiifPresentationVersion/createMany",
+    {
+      schema: {
+        params: {
+          type: "object",
+          properties: {
+            iiifPresentationVersion: iiifPresentationVersionSchema
+          }
+        },
+        body: routeAnnotationCreateManySchema,
+        response: responsePostSchema
+      }
+    },
+    async (request, reply) => {
+      const
+        { iiifPresentationVersion } = request.params,
+        body = maybeToArray(request.body),  // convert to an array to have a homogeneous data structure
+        insertResponseArray = [];
+
+      // data to actually insert (body with resolved URIs, if the body is  `annotationListOrPageUri` or `annotationListOrPageUriArray`)
+      let annotationsArray = [];
+
+      try {
+        // if we received `annotationListOrPageUri` or `annotationListOrPageUriArray`, fetch objects
+        const asUri = body.find(item => objectHasKey(item, "uri")) !== undefined;
+        if (asUri) {
+          annotationsArray = await Promise.all(
+            body.map(async (item) =>
+              fetch(item.uri).then(r => r.json()))
+          );
+        } else {
+          annotationsArray = body;
+        }
+
+        validateAnnotationArrayVersion(iiifPresentationVersion, annotationsArray);
+
+        // insert
+        if ( iiifPresentationVersion === 2 ) {
+          await Promise.all(annotationsArray.map(
+            async (annotationList) => {
+              const r = await annotations2.insertAnnotationList(annotationList);
+              insertResponseArray.push(r);
+            }
+          ));
+          return reduceInsertResponseArray(insertResponseArray);
+        } else {
+          annotations3.notImplementedError();
+        }
+
+      } catch (err) {
+        returnError(request, reply, err, request.body);
+      }
+    }
+  )
+
+  done();
+
+}
+
+export default fastifyPlugin(annotationsRoutes);

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

@@ -0,0 +1,180 @@
+import test from "node:test";
+
+import build from "#src/app.js";
+
+import { v4 as uuid4 } from "uuid";
+
+import { inspectObj, isObject, getRandomItem, visibleLog } from "#utils/utils.js"
+import { testPostRouteCurry, testDeleteRouteCurry, injectTestAnnotations } from "#utils/testUtils.js";
+
+/** @typedef {import("#types").NodeTestType} NodeTestType */
+/** @typedef {import("#types").FastifyInstanceType} FastifyInstanceType */
+/** @typedef {import("#types").FastifyReplyType} FastifyReplyType */
+/** @typedef {import("#types").DataOperationsType} DataOperationsType */
+
+test("test annotation Routes", async (t) => {
+
+  const
+    fastify = await build("test"),
+    testPostRoute = testPostRouteCurry(fastify),
+    testPostRouteCreate = testPostRoute("insert"),
+    testPostRouteUpdate = testPostRoute("update"),
+    testDeleteRoute = testDeleteRouteCurry(fastify),
+    testPostRouteCreateSuccess = testPostRouteCreate(true),
+    testPostRouteCreateFailure = testPostRouteCreate(false),
+    testPostRouteUpdateSuccess = testPostRouteUpdate(true),
+    testPostRouteUpdateFailure = testPostRouteUpdate(false),
+    {
+      annotationListUri,
+      annotationListUriArray,
+      annotationList,
+      annotationListArray,
+      annotationListUriInvalid,
+      annotationListUriArrayInvalid
+    } = 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 /annotations/:iiifPresentationVersion/createMany", async (t) => {
+    // truncate the contents of `annotationListArray` to avoid an `fst_err_ctp_body_too_large` error
+    // `https://fastify.dev/docs/latest/Reference/Errors/#fst_err_ctp_body_too_large`
+    const annotationListArrayLimit = annotationListArray.map(a => {
+      a.resources = a.resources.length > 500 ? a.resources.slice(0,500) : a.resources
+      return a;
+    });
+
+    //NOTE: we can't do Promise.all because it causes a data race that can cause a failure of unique constraints (i.e., on manifests '@id')
+    const data = [
+      [[ annotationListUri, annotationListUriArray, annotationList, annotationListArrayLimit ], testPostRouteCreateSuccess],
+      [[ annotationListUriInvalid, annotationListUriArrayInvalid ], testPostRouteCreateFailure]
+    ];
+    for ( let i=0; i<data.length; i++ ) {
+      let [ testData, func ] = data.at(i);
+      for ( let i=0; i<testData.length; i++ ) {
+        await func(t, "/annotations/2/createMany", testData.at(i));
+      }
+    }
+  })
+
+  await t.test("test route /annotations/:iiifPresentationVersion/create", async (t) => {
+    //NOTE: we can't do Promise.all because it causes a data race that can cause a failure of unique constraints (i.e., on manifests '@id')
+    const data = [
+      [fastify.fileServer.annotations2Valid, testPostRouteCreateSuccess],
+      [fastify.fileServer.annotations2Invalid, testPostRouteCreateFailure],
+    ]
+    for ( let i=0; i<data.length; i++ ) {
+      let [ testData, func ] = data.at(i);
+      for ( let i=0; i<testData.length; i++ ) {
+        await func(t, "/annotations/2/create", testData.at(i));
+      }
+    };
+  })
+
+  await t.test("test route /annotations/:iiifPresentationVersion/update", async (t) => {
+    const updatePipeline = async (annotation, success) => {
+      // update the annotation
+      const
+        newLabel = `label-${uuid4()}`,
+        newBody = {
+          "@type": "cnt:ContentAsText",
+          format: "text/html",
+          value: "<p>What a grand pleasure it is to have updated this annotation !</p>"
+        };
+      annotation.label = newLabel;
+      annotation.resource = newBody;
+      if (!success) {
+        annotation["@type"] = "invalidType";
+      }
+      success
+        ? await testPostRouteUpdateSuccess(t, "/annotations/2/update", annotation)
+        : await testPostRouteUpdateFailure(t, "/annotations/2/update", annotation);
+    }
+
+    // insert valid documents and retrieve an annotation to update.
+    const
+      [ insertedCount, insertedIds ] = await injectTestAnnotations(fastify, t, annotationList),
+      idToUpdate = getRandomItem(insertedIds),  // get a random item
+      annotation = await fastify.mongo.db.collection("annotations2").findOne(
+        { "@id": idToUpdate },
+        { projection: { _id: 0 }}
+      );
+
+    await updatePipeline(annotation, true);
+    await updatePipeline(annotation, false);
+    return;
+  });
+
+  await t.test("test route /annotations/:iiifPresentationVersion/search", async (t) => {
+    await injectTestAnnotations(fastify, t, annotationList);
+    await Promise.all(
+      // `asAnnotationList` is a boolean defining if we should return an array or an annotationList.
+      [false, true].map(async (asAnnotationList) => {
+
+        const
+          annotation = await getRandomItem(
+            await fastify.mongo.db.collection("annotations2").find().toArray()
+          ),
+          canvasId = annotation.on.full,
+          r = await fastify.inject({
+            method: "GET",
+            url: `/annotations/2/search?uri=${canvasId}&asAnnotationList=${asAnnotationList}`
+          }),
+          body = await r.json();
+
+        t.assert.deepStrictEqual(r.statusCode, 200);
+        if ( asAnnotationList ) {
+          // we have aldready defined responses for both cases of `asAnnotationList`, so we just need to check that the response is of a proper type
+          t.assert.deepStrictEqual(Array.isArray(body), false);
+        } else {
+          t.assert.deepStrictEqual(Array.isArray(body), true)
+          t.assert.deepStrictEqual(body.length > 0, true);
+        }
+
+      })
+    )
+
+  })
+
+  await t.test("test route /data/:iiifPresentationVersion/:manifestShortId/annotation/:annotationShortId", async (t) => {
+    await injectTestAnnotations(fastify, t, annotationList);
+    const annotationId = await getRandomItem(
+      await fastify.mongo.db.collection("annotations2").find().toArray()
+    )["@id"];
+    await Promise.all(
+      // if shouldExist, search an annotation that exists, otherwise, search an annotation that does not exist. test accordingly.
+      [true, false].map(async (shouldExist) => {
+        const
+          annotationIdQuery =
+            shouldExist
+              ? annotationId.replace(process.env.APP_BASE_URL, "")
+              : annotationId.replace(process.env.APP_BASE_URL, "") + "string_that_does_not_exist_in_the_db",
+          r = await fastify.inject({
+            method: "GET",
+            url: annotationIdQuery
+          }),
+          body = await r.json();
+
+        t.assert.deepStrictEqual(r.statusCode, 200);
+        if ( shouldExist ) {
+          t.assert.deepStrictEqual(body["@id"]===annotationId, true);
+        } else {
+          t.assert.deepStrictEqual(Object.keys(body).length === 0, true);
+        }
+      })
+    )
+  })
+
+  return
+})