jskos-server 2.4.0

package/errors/index.js

@@ -0,0 +1,94 @@
+/**
+ * Errors.
+ *
+ * If possible, provide a more detailed error message when one of these errors is used.
+ */
+
+export class EntityNotFoundError extends Error {
+  constructor(message, id) {
+    message = message || `The requested entity ${id} could not be found.`
+    super(message)
+    this.statusCode = 404
+  }
+}
+
+export class MalformedBodyError extends Error {
+  constructor(message) {
+    message = message || "The body of the request is malformed."
+    super(message)
+    this.statusCode = 400
+  }
+}
+
+export class MalformedRequestError extends Error {
+  constructor(message) {
+    message = message || "The request is malformed (missing parameter etc.)."
+    super(message)
+    this.statusCode = 400
+  }
+}
+
+export class DuplicateEntityError extends Error {
+  constructor(message, id) {
+    message = message || `The entity ${id} already exists in the database.`
+    super(message)
+    this.statusCode = 422
+  }
+}
+
+export class InvalidBodyError extends Error {
+  constructor(message) {
+    message = message || "The body of the request is well formed, but could not be validated."
+    super(message)
+    this.statusCode = 422
+  }
+}
+
+export class CreatorDoesNotMatchError extends Error {
+  constructor(message) {
+    message = message || "Access to this ressource is not allowed for you (but might be for other users)."
+    super(message)
+    this.statusCode = 403
+  }
+}
+
+export class BackendError extends Error {
+  constructor(message) {
+    message = message || "There was an error with the backend. Please try again later."
+    super(message)
+    this.statusCode = 500
+  }
+}
+
+export class DatabaseAccessError extends BackendError {
+  constructor(message) {
+    message = message || "There was an error accessing the database. Please try again later."
+    super(message)
+  }
+}
+
+export class DatabaseInconsistencyError extends BackendError {
+  constructor(message) {
+    if (message) {
+      message += " Please contact us with this error message at coli-conc@gbv.de or open an issue on GitHub. Thanks!"
+    } else {
+      message = "There was an inconsistency error with the database. Please try again later."
+    }
+    super(message)
+  }
+}
+
+export class ConfigurationError extends BackendError {
+  constructor(message) {
+    message = message || "There was an error with the server configuration. Please contact the server administrator and try again later."
+    super(message)
+  }
+}
+
+export class ForbiddenAccessError extends Error {
+  constructor(message) {
+    message = message || "Access is forbidden."
+    super(message)
+    this.statusCode = 403
+  }
+}

package/eslint.config.js

@@ -0,0 +1,17 @@
+import gbv from "eslint-config-gbv"
+
+// Extend base config and add ignores for Docker data
+export default [
+  ...gbv,
+  {
+    ignores: [
+      "docker/data/**",
+    ],
+  },
+  {
+    languageOptions: {
+      globals: { mocha: "readable" },
+    },
+  },
+]
+

package/index.js

@@ -0,0 +1,10 @@
+import { validateConfig, setupConfig } from "./config/setup.js"
+import { createServices as _createServices } from "./services/index.js"
+
+// TODO: move this into createServices
+function createServices(config) {
+  setupConfig(config)
+  return _createServices(config)
+}
+
+export { validateConfig, createServices }

package/models/annotations.js

@@ -0,0 +1,13 @@
+import mongoose from "mongoose"
+const Schema = mongoose.Schema
+
+const annotationSchema = new Schema({
+  _id: String,
+  id: String,
+}, {
+  versionKey: false,
+  strict: false,
+  autoIndex: false,
+})
+
+export const Annotation = mongoose.model("Annotation", annotationSchema)

package/models/concepts.js

@@ -0,0 +1,12 @@
+import mongoose from "mongoose"
+const Schema = mongoose.Schema
+
+const conceptSchema = new Schema({
+  _id: String,
+}, {
+  versionKey: false,
+  strict: false,
+  autoIndex: false,
+})
+
+export const Concept = mongoose.model("Concept", conceptSchema)

package/models/concordances.js

@@ -0,0 +1,12 @@
+import mongoose from "mongoose"
+const Schema = mongoose.Schema
+
+const concordanceSchema = new Schema({
+  _id: String,
+}, {
+  versionKey: false,
+  strict: false,
+  autoIndex: false,
+})
+
+export const Concordance = mongoose.model("Concordance", concordanceSchema)

package/models/index.js

@@ -0,0 +1,33 @@
+import { Annotation } from "./annotations.js"
+import { Concept } from "./concepts.js"
+import { Concordance } from "./concordances.js"
+import { Mapping } from "./mappings.js"
+import { Meta } from "./meta.js"
+import { Scheme } from "./schemes.js"
+import { Registry } from "./registries.js"
+
+export {
+  Annotation,
+  Concept,
+  Concordance,
+  Mapping,
+  Meta,
+  Scheme,
+  Registry,
+}
+
+export const models = {
+  scheme: Scheme,
+  concept: Concept,
+  concordance: Concordance,
+  mapping: Mapping,
+  annotation: Annotation,
+  registry: Registry,
+}
+
+Object.keys(models).forEach(type => {
+  const plural = type === "registry" ? "registries" : `${type}s`
+  Object.defineProperty(models, plural, {
+    get: () => models[type],
+  })
+})

package/models/mappings.js

@@ -0,0 +1,20 @@
+import mongoose from "mongoose"
+import jskos from "jskos-tools"
+
+const Schema = mongoose.Schema
+
+const mappingSchema = new Schema({
+  _id: String,
+}, {
+  versionKey: false,
+  strict: false,
+  autoIndex: false,
+})
+
+mappingSchema.pre("save", function(next) {
+  // Add mapping identifier
+  this.set("identifier", jskos.addMappingIdentifiers(this).identifier)
+  next()
+})
+
+export const Mapping = mongoose.model("Mapping", mappingSchema)

package/models/meta.js

@@ -0,0 +1,21 @@
+import mongoose from "mongoose"
+const Schema = mongoose.Schema
+
+const metaSchema = new Schema({
+  // makes sure that there's only one entry in the collection
+  _default: {
+    type: Boolean,
+    default: true,
+    required: true,
+    unique: true,
+    immutable: true,
+  },
+  version: String,
+}, {
+  versionKey: false,
+  strict: false,
+  collection: "meta",
+  autoIndex: false,
+})
+
+export const Meta = mongoose.model("meta", metaSchema)

package/models/registries.js

@@ -0,0 +1,12 @@
+import mongoose from "mongoose"
+const Schema = mongoose.Schema
+
+const registrySchema = new Schema({
+  _id: String,
+}, {
+  versionKey: false,
+  strict: false,
+  autoIndex: false,
+})
+
+export const Registry = mongoose.model("Registry", registrySchema)

package/models/schemes.js

@@ -0,0 +1,12 @@
+import mongoose from "mongoose"
+const Schema = mongoose.Schema
+
+const terminologySchema = new Schema({
+  _id: String,
+}, {
+  versionKey: false,
+  strict: false,
+  autoIndex: false,
+})
+
+export const Scheme = mongoose.model("Terminology", terminologySchema)

package/package.json

@@ -0,0 +1,91 @@
+{
+  "name": "jskos-server",
+  "version": "2.4.0",
+  "apiVersion": "2.2",
+  "description": "JSKOS database and web service",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gbv/jskos-server.git"
+  },
+  "type": "module",
+  "exports": "./index.js",
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "test": "NODE_ENV=test mocha --exit --timeout 60000 --slow 2000",
+    "coverage": "NODE_ENV=test c8 --reporter=text --skip-full mocha --exit --timeout 60000 --slow 2000",
+    "start": "nodemon server.js",
+    "mongodb": "./bin/mongodb.js",
+    "lint": "eslint",
+    "fix": "eslint --fix",
+    "lint-staged": "lint-staged",
+    "prepare": "husky || true",
+    "import": "./bin/import.js",
+    "import-batch": "func() { tr '\\n' '\\0' < \"$2\"  | xargs -0 -n1 ./bin/import.js $1; }; func",
+    "reset": "./bin/reset.js",
+    "upgrade": "./bin/upgrade.js",
+    "extra": "./bin/extra.js",
+    "yesno": "node -e \"const yesno = require('yesno'); yesno({ question: 'Are you sure you want to continue?' }).then(ok => process.exit(ok ? 0 : 1));\"",
+    "release": "test $(git rev-parse --abbrev-ref HEAD) = dev && git pull && npm test && npm version $SEMVER && npm run --silent yesno && (git push && git checkout main && git merge dev && git push --follow-tags && git checkout dev) || (git tag -d $(git describe --tags) && git reset --hard HEAD~1)",
+    "release:patch": "SEMVER=patch npm run release",
+    "release:minor": "SEMVER=minor npm run release",
+    "release:major": "SEMVER=major npm run release"
+  },
+  "lint-staged": {
+    "**/*.js": [
+      "eslint --fix"
+    ],
+    "*.js": [
+      "eslint --fix"
+    ]
+  },
+  "author": "",
+  "license": "MIT",
+  "devDependencies": {
+    "c8": "^10.1.3",
+    "chai": "^6.2.2",
+    "chai-as-promised": "^8.0.2",
+    "chai-http": "^5.1.1",
+    "eslint": "~9.39",
+    "eslint-config-gbv": "~2.7",
+    "esmock": "^2.6.9",
+    "express-ws": "^5.0.2",
+    "glob": "^13.0.0",
+    "husky": "^9.1.7",
+    "jsonwebtoken": "^9.0.2",
+    "lint-staged": "^16.2.7",
+    "mocha": "^11.0.1",
+    "mongodb-memory-server": "^11.0.1",
+    "ws": "^8.18.2"
+  },
+  "dependencies": {
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
+    "axios": "^1.7.9",
+    "cocoda-sdk": "^3.4.12",
+    "dotenv": "^16.4.7",
+    "ejs": "^3.1.10",
+    "express": "^5.2.1",
+    "express-basic-auth": "^1.2.1",
+    "express-ws": "^5.0.2",
+    "ipaddr.js": "^2.2.0",
+    "jskos-tools": "^1.0.43",
+    "jskos-validate": "1.2.1",
+    "json-anystream": "^2.0.1",
+    "JSONStream": "^1.3.5",
+    "lodash": "^4.17.21",
+    "meow": "^14.0.0",
+    "mongodb": "^7.0.0",
+    "mongoose": "^9.1.2",
+    "morgan": "^1.10.0",
+    "nocache": "^4.0.0",
+    "nodemon": "^3.1.7",
+    "passport": "~0.7.0",
+    "passport-anonymous": "^1.0.1",
+    "passport-jwt": "^4.0.1",
+    "portfinder": "^1.0.32",
+    "uuid": "^13.0.0",
+    "yesno": "^0.4.0"
+  }
+}

package/routes/annotations.js

@@ -0,0 +1,83 @@
+import express from "express"
+import { AnnotationService } from "../services/annotations.js"
+import * as utils from "../utils/middleware.js"
+import { wrapAsync } from "../utils/middleware.js"
+import { useAuth } from "../utils/auth.js"
+import { readRoute, createRoute, updateRoute, deleteRoute } from "./common.js"
+
+export default config => {
+  const router = express.Router()
+  const { annotations } = config
+  if (!annotations) {
+    return router
+  }
+
+  const service = new AnnotationService(config)
+
+  readRoute(router, "/", annotations.read, service, "annotations")
+  createRoute(router, "/", annotations.create, service)
+  updateRoute(router, "/", annotations.update, service)
+  deleteRoute(router, "/", annotations.delete, service)
+
+  if (annotations.read) {
+    router.get(
+      "/:_id",
+      useAuth(annotations.read.auth),
+      wrapAsync(async req => service.getItem(req.params._id)),
+      utils.adjust,
+      utils.returnJSON,
+    )
+  }
+
+  if (annotations.update) {
+    router.put(
+      "/:_id",
+      useAuth(annotations.update.auth),
+      utils.bodyParser,
+      wrapAsync(async (req) => {
+        return await service.updateItem({
+          _id: req.params._id,
+          body: req.body,
+          user: req.user,
+          existing: req.existing,
+        })
+      }),
+      utils.adjust,
+      utils.returnJSON,
+    )
+
+    router.patch(
+      "/:_id",
+      useAuth(annotations.update.auth),
+      utils.bodyParser,
+      wrapAsync(async (req) => {
+        return await service.patchAnnotation({
+          _id: req.params._id,
+          body: req.body,
+          user: req.user,
+          existing: req.existing,
+        })
+      }),
+      utils.adjust,
+      utils.returnJSON,
+    )
+  }
+
+  if (annotations.delete) {
+    router.delete(
+      "/:_id",
+      useAuth(annotations.delete.auth),
+      utils.bodyParser,
+      wrapAsync(async (req) => {
+        return await service.deleteItem({
+          uri: req.params._id,
+          user: req.user,
+          existing: req.existing,
+        })
+      }),
+      (req, res) => res.sendStatus(204),
+    )
+  }
+
+  return router
+}

package/routes/common.js

@@ -0,0 +1,86 @@
+import { useAuth } from "../utils/auth.js"
+import { bodyParser, wrapAsync, supportDownloadFormats, returnJSON, addPaginationHeaders, handleDownload, wrapDownload, adjust } from "../utils/middleware.js"
+
+export function readRoute(router, path, config, service, name, formats=[]) {
+  if (config) {
+    router.get(
+      path,
+      useAuth(config.auth),
+      supportDownloadFormats(formats),
+      wrapAsync(async req => service.queryItems(req.query)),
+      wrapDownload(addPaginationHeaders, false),
+      wrapDownload(adjust, false),
+      wrapDownload(returnJSON, false),
+      wrapDownload(handleDownload(name), true),
+    )
+  }
+}
+
+export function createRoute(router, path, config, service) {
+  if (config) {
+    router.post(
+      path,
+      useAuth(config.auth),
+      bodyParser,
+      wrapAsync(async (req) => {
+        return await service.createItem({
+          bodyStream: req.anystream,
+          user: req.user,
+          bulk: req.query?.bulk,
+          scheme: req.query?.scheme,
+          setApi: req.query?.setApi, // TODO: this is not documented
+        })
+      }),
+      adjust,
+      returnJSON,
+    )
+  }
+}
+
+export function updateRoute(router, path, config, service) {
+  if (config) {
+    router.put(
+      path,
+      useAuth(config.auth),
+      bodyParser,
+      wrapAsync(async req => service.updateItems({
+        body: req.body,
+        existing: req.existing,
+        setApi: req.query?.setApi, // TODO: this is not documented
+      })),
+      adjust,
+      returnJSON,
+    )
+  }
+}
+
+export function deleteRoute(router, path, config, service) {
+  if (config) {
+    router.delete(
+      path,
+      useAuth(config.auth),
+      bodyParser,
+      wrapAsync(async (req) => {
+        return await service.deleteItem({
+          uri: req.query.uri,
+          existing: req.existing,
+          setApi: req.query?.setApi, // TODO: this is not documented
+        })
+      }),
+      (req, res) => res.sendStatus(204),
+    )
+  }
+}
+
+export function suggestRoute(router, path, config, service) {
+  if (config) {
+    router.get(
+      path,
+      useAuth(config.auth),
+      supportDownloadFormats([]),
+      wrapAsync(async req => service.getSuggestions(req.query)),
+      addPaginationHeaders,
+      returnJSON,
+    )
+  }
+}

package/routes/concepts.js

@@ -0,0 +1,64 @@
+import express from "express"
+import { ConceptService } from "../services/concepts.js"
+import * as utils from "../utils/middleware.js"
+import { wrapAsync } from "../utils/middleware.js"
+import { useAuth } from "../utils/auth.js"
+import { readRoute, createRoute, updateRoute, deleteRoute, suggestRoute } from "./common.js"
+
+export default config => {
+  const router = express.Router()
+  const { concepts } = config
+  if (!concepts) {
+    return concepts
+  }
+
+  const service = new ConceptService(config)
+
+  readRoute(router, "/concepts", concepts.read, service, "concepts", ["json", "ndjson"])
+  createRoute(router, "/concepts", concepts.create, service)
+  updateRoute(router, "/concepts", concepts.update, service)
+  deleteRoute(router, "/concepts", concepts.delete, service)
+
+  if (concepts.read) {
+    // Add these routes both with and without the /concepts prefix.
+    // TODO for 3.0: The routes without should be deprecated in the next major release.
+    // See also: https://github.com/gbv/jskos-server/issues/193#issuecomment-1508038432
+
+    for (const prefix of ["", "/concepts"]) {
+
+      router.get(
+        prefix + "/narrower",
+        useAuth(concepts.read.auth),
+        utils.supportDownloadFormats([]),
+        wrapAsync(async req => service.getNarrower(req.query)),
+        utils.addPaginationHeaders,
+        utils.adjust,
+        utils.returnJSON,
+      )
+
+      router.get(
+        prefix + "/ancestors",
+        useAuth(concepts.read.auth),
+        utils.supportDownloadFormats([]),
+        wrapAsync(async req => service.getAncestors(req.query)),
+        utils.addPaginationHeaders,
+        utils.adjust,
+        utils.returnJSON,
+      )
+
+      suggestRoute(router, prefix + "/suggest", concepts.read, service)
+
+      router.get(
+        prefix + "/search",
+        useAuth(concepts.read.auth),
+        utils.supportDownloadFormats([]),
+        wrapAsync(async req => await service.search(req.query)),
+        utils.addPaginationHeaders,
+        utils.adjust,
+        utils.returnJSON,
+      )
+    }
+  }
+
+  return router
+}

package/routes/concordances.js

@@ -0,0 +1,86 @@
+import express from "express"
+import { ConcordanceService } from "../services/concordances.js"
+import * as utils from "../utils/middleware.js"
+import { wrapAsync, wrapDownload } from "../utils/middleware.js"
+import { useAuth } from "../utils/auth.js"
+import { readRoute, createRoute, updateRoute, deleteRoute } from "./common.js"
+
+export default config => {
+  const router = express.Router()
+  const { concordances } = config
+  if (!concordances) {
+    return router
+  }
+
+  const service = new ConcordanceService(config)
+
+  readRoute(router, "/", concordances.read, service, "concordances", ["json", "ndjson"])
+
+  if (concordances.read) {
+    router.get(
+      "/:_id",
+      useAuth(concordances.read.auth),
+      utils.supportDownloadFormats(["json", "ndjson"]),
+      wrapAsync(async req => service.getItem(req.params._id)),
+      wrapDownload(utils.adjust, false),
+      wrapDownload(utils.returnJSON, false),
+      wrapDownload(utils.handleDownload("concordance"), true),
+    )
+  }
+
+  createRoute(router, "/", concordances.create, service)
+  updateRoute(router, "/", concordances.update, service)
+  deleteRoute(router, "/", concordances.delete, service)
+
+  if (concordances.update) {
+    router.put(
+      "/:_id",
+      useAuth(concordances.update.auth),
+      utils.bodyParser,
+      wrapAsync(async (req) => {
+        return await service.putConcordance({
+          _id: req.params._id,
+          body: req.body,
+          user: req.user,
+          existing: req.existing,
+        })
+      }),
+      utils.adjust,
+      utils.returnJSON,
+    )
+
+    router.patch(
+      "/:_id",
+      useAuth(concordances.update.auth),
+      utils.bodyParser,
+      wrapAsync(async (req) => {
+        return await service.patchConcordance({
+          _id: req.params._id,
+          body: req.body,
+          user: req.user,
+          existing: req.existing,
+        })
+      }),
+      utils.adjust,
+      utils.returnJSON,
+    )
+  }
+
+  if (concordances.delete) {
+    router.delete(
+      "/:_id",
+      useAuth(concordances.delete.auth),
+      utils.bodyParser,
+      wrapAsync(async (req) => {
+        return await service.deleteItem({
+          _id: req.params._id,
+          user: req.user,
+          existing: req.existing,
+        })
+      }),
+      (req, res) => res.sendStatus(204),
+    )
+  }
+
+  return router
+}