fix: paths and cache (#22)

Author: jurijat

CHANGELOG.md

@@ -4,6 +4,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ## [unreleased]
 
+## [0.8.0] - 2025-04-08
+
+### Added
+
+- Standardized path handling
+
+### Changed
+
+- Improved Caching
+- Encapsulated business logic
+
 ## [0.7.4] - 2025-03-25
 
 - Workflow file changes

README.md

@@ -6,13 +6,15 @@ This project helps to expose static metadata using [Open Resource Discovery](htt
 
 ## Usage
 
+Replace "/path-to-your-metadata" with the directory, that has your ORD Documents.
+
 ### Via **Docker**
 
 1. **Local** (default: open)
 
 ```bash
 docker run -p 8080:8080 \
-           -v "$(pwd)/example:/app/data" \
+           -v "$(pwd)/path-to-your-metadata:/app/data" \
            ghcr.io/open-resource-discovery/provider-server:latest \
            -d /app/data \
            --base-url 'http://127.0.0.1:8080'
@@ -21,7 +23,7 @@ docker run -p 8080:8080 \
 2. **Local** (basic auth)
 
 ```bash
-docker run -p 8080:8080 -v "$(pwd)/example:/app/data" \
+docker run -p 8080:8080 -v "$(pwd)/path-to-your-metadata:/app/data" \
   -e BASIC_AUTH='{"admin":"$2y$05$TjeC./ljKi7VLTBbzjTVyOi6lQBYpzfXiZSfJiGECHVi0eEN6/QG."}' \
   ghcr.io/open-resource-discovery/provider-server:latest \
   -d /app/data --auth basic --base-url 'http://127.0.0.1:8080'
@@ -50,13 +52,13 @@ docker run -p 8080:8080 \
 1. **Local** (default: open)
 
 ```bash
- npx @open-resource-discovery/provider-server -d ./example --base-url 'http://127.0.0.1:8080'
+ npx @open-resource-discovery/provider-server -d /path-to-your-metadata --base-url 'http://127.0.0.1:8080'
 ```
 
 2. **Local** (basic auth)
 
 ```bash
- BASIC_AUTH='{"admin":"$2y$05$TjeC./ljKi7VLTBbzjTVyOi6lQBYpzfXiZSfJiGECHVi0eEN6/QG."}' npx @open-resource-discovery/provider-server -d ./example --auth basic --base-url 'http://127.0.0.1:8080'
+ BASIC_AUTH='{"admin":"$2y$05$TjeC./ljKi7VLTBbzjTVyOi6lQBYpzfXiZSfJiGECHVi0eEN6/QG."}' npx @open-resource-discovery/provider-server -d /path-to-your-metadata --auth basic --base-url 'http://127.0.0.1:8080'
 ```
 
 3. **GitHub** (open)

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-resource-discovery/provider-server",
-  "version": "0.7.4",
+  "version": "0.8.0",
   "description": "A CLI application or server that takes multiple ORD documents and other metadata files and exposes them as a ORD Provider implementation (ORD Document API)",
   "engines": {
     "node": ">=22.8.0",

package.json

@@ -3,7 +3,7 @@ import { ORDConfiguration, ORDDocument } from "@open-resource-discovery/specific
 import path from "path";
 import { OptAuthMethod, OptSourceType } from "src/model/cli.js";
 import { startProviderServer } from "src/server.js";
-import { ORD_DOCUMENTS_SUB_DIRECTORY } from "../constant.js";
+import { PATH_CONSTANTS } from "../constant.js";
 
 // Mock bcrypt to avoid native module issues in tests
 jest.mock("bcryptjs", () => ({
@@ -22,7 +22,7 @@ describe("End-to-End Testing", () => {
   beforeAll(async () => {
     shutdownServer = await startProviderServer({
       ordDirectory: path.join(process.cwd(), "src/__tests__/test-files"),
-      ordDocumentsSubDirectory: ORD_DOCUMENTS_SUB_DIRECTORY,
+      ordDocumentsSubDirectory: PATH_CONSTANTS.DOCUMENTS_SUBDIRECTORY,
       sourceType: OptSourceType.Local,
       baseUrl: SERVER_URL,
       host: "0.0.0.0",
@@ -40,7 +40,7 @@ describe("End-to-End Testing", () => {
 
   it("should complete full user journey", async () => {
     // 1. Discover API
-    const configResponse = await fetch(`${SERVER_URL}/.well-known/open-resource-discovery`);
+    const configResponse = await fetch(`${SERVER_URL}${PATH_CONSTANTS.WELL_KNOWN_ENDPOINT}`);
     expect(configResponse.status).toBe(200);
     const config = (await configResponse.json()) as ORDConfiguration;
 

src/__tests__/e2e.test.ts

@@ -1,12 +1,7 @@
 import { afterAll, beforeAll, describe, expect, it } from "@jest/globals";
 import { ORDConfiguration, ORDDocument, ORDV1DocumentDescription } from "@open-resource-discovery/specification";
 import path from "path";
-import {
-  ORD_DOCUMENTS_SUB_DIRECTORY,
-  ORD_DOCUMENTS_URL_PATH,
-  ORD_SERVER_PREFIX_PATH,
-  WELL_KNOWN_ENDPOINT,
-} from "src/constant.js";
+import { PATH_CONSTANTS } from "src/constant.js";
 import { OptAuthMethod, OptSourceType } from "src/model/cli.js";
 import { ProviderServerOptions, startProviderServer } from "src/server.js";
 
@@ -29,7 +24,7 @@ describe("Server Integration", () => {
   beforeAll(async () => {
     const options: ProviderServerOptions = {
       ordDirectory: LOCAL_DIRECTORY,
-      ordDocumentsSubDirectory: ORD_DOCUMENTS_SUB_DIRECTORY,
+      ordDocumentsSubDirectory: PATH_CONSTANTS.DOCUMENTS_SUBDIRECTORY,
       sourceType: OptSourceType.Local,
       host: TEST_HOST,
       port: TEST_PORT,
@@ -49,15 +44,15 @@ describe("Server Integration", () => {
 
   describe("Well-Known Endpoint", () => {
     it("should return ORD configuration without authentication", async () => {
-      const response = await fetch(`${SERVER_URL}${WELL_KNOWN_ENDPOINT}`);
+      const response = await fetch(`${SERVER_URL}${PATH_CONSTANTS.WELL_KNOWN_ENDPOINT}`);
 
       expect(response.status).toBe(200);
       const data = await response.json();
       expect(data).toHaveProperty("openResourceDiscoveryV1");
     });
 
     it("should list all available documents in configuration", async () => {
-      const response = await fetch(`${SERVER_URL}${WELL_KNOWN_ENDPOINT}`);
+      const response = await fetch(`${SERVER_URL}${PATH_CONSTANTS.WELL_KNOWN_ENDPOINT}`);
       const data = (await response.json()) as ORDConfiguration;
 
       expect(data.openResourceDiscoveryV1.documents).toBeDefined();
@@ -73,13 +68,13 @@ describe("Server Integration", () => {
 
   describe("ORD Documents Endpoint", () => {
     it("should require authentication for accessing documents", async () => {
-      const response = await fetch(`${SERVER_URL}${ORD_DOCUMENTS_URL_PATH}/ref-app-example-1`);
+      const response = await fetch(`${SERVER_URL}${PATH_CONSTANTS.DOCUMENTS_URL_PATH}/ref-app-example-1`);
       expect(response.status).toBe(401);
     });
 
     it("should return document with valid authentication", async () => {
       const credentials = Buffer.from("admin:secret").toString("base64");
-      const response = await fetch(`${SERVER_URL}${ORD_DOCUMENTS_URL_PATH}/ref-app-example-1`, {
+      const response = await fetch(`${SERVER_URL}${PATH_CONSTANTS.DOCUMENTS_URL_PATH}/ref-app-example-1`, {
         headers: {
           Authorization: `Basic ${credentials}`,
         },
@@ -95,7 +90,7 @@ describe("Server Integration", () => {
       const credentials = Buffer.from("admin:secret").toString("base64");
       const headers = { Authorization: `Basic ${credentials}` };
 
-      const configResponse = await fetch(`${SERVER_URL}${WELL_KNOWN_ENDPOINT}`);
+      const configResponse = await fetch(`${SERVER_URL}${PATH_CONSTANTS.WELL_KNOWN_ENDPOINT}`);
       const config = (await configResponse.json()) as ORDConfiguration;
       const documents = config.openResourceDiscoveryV1.documents!;
 
@@ -110,7 +105,7 @@ describe("Server Integration", () => {
 
     it("should handle document names with special characters", async () => {
       const credentials = Buffer.from("admin:secret").toString("base64");
-      const response = await fetch(`${SERVER_URL}${ORD_DOCUMENTS_URL_PATH}/ref-app-example-1`, {
+      const response = await fetch(`${SERVER_URL}${PATH_CONSTANTS.DOCUMENTS_URL_PATH}/ref-app-example-1`, {
         headers: {
           Authorization: `Basic ${credentials}`,
         },
@@ -121,7 +116,7 @@ describe("Server Integration", () => {
 
     it("should correctly extract document name when URL contains .json extension", async () => {
       const credentials = Buffer.from("admin:secret").toString("base64");
-      const response = await fetch(`${SERVER_URL}${ORD_DOCUMENTS_URL_PATH}/ref-app-example-1.json`, {
+      const response = await fetch(`${SERVER_URL}${PATH_CONSTANTS.DOCUMENTS_URL_PATH}/ref-app-example-1.json`, {
         headers: {
           Authorization: `Basic ${credentials}`,
         },
@@ -135,7 +130,7 @@ describe("Server Integration", () => {
 
     it("should correctly extract document name when URL contains dots and a .json extension", async () => {
       const credentials = Buffer.from("admin:secret").toString("base64");
-      const response = await fetch(`${SERVER_URL}${ORD_DOCUMENTS_URL_PATH}/sap.ref-app-example.json`, {
+      const response = await fetch(`${SERVER_URL}${PATH_CONSTANTS.DOCUMENTS_URL_PATH}/sap.ref-app-example.json`, {
         headers: {
           Authorization: `Basic ${credentials}`,
         },
@@ -151,7 +146,7 @@ describe("Server Integration", () => {
   describe("Static Resources", () => {
     it("should serve static files with authentication", async () => {
       const credentials = Buffer.from("admin:secret").toString("base64");
-      const response = await fetch(`${SERVER_URL}${ORD_SERVER_PREFIX_PATH}/astronomy/v1/openapi/oas3.json`, {
+      const response = await fetch(`${SERVER_URL}${PATH_CONSTANTS.SERVER_PREFIX}/astronomy/v1/openapi/oas3.json`, {
         headers: {
           Authorization: `Basic ${credentials}`,
         },
@@ -171,7 +166,7 @@ describe("Server Integration", () => {
   describe("Error Handling", () => {
     it("should return 404 for non-existent documents", async () => {
       const credentials = Buffer.from("admin:secret").toString("base64");
-      const response = await fetch(`${SERVER_URL}${ORD_DOCUMENTS_URL_PATH}/non-existent-document`, {
+      const response = await fetch(`${SERVER_URL}${PATH_CONSTANTS.DOCUMENTS_URL_PATH}/non-existent-document`, {
         headers: {
           Authorization: `Basic ${credentials}`,
         },
@@ -184,7 +179,7 @@ describe("Server Integration", () => {
 
     it("should return 401 with invalid credentials", async () => {
       const credentials = Buffer.from("admin:wrong").toString("base64");
-      const response = await fetch(`${SERVER_URL}${ORD_DOCUMENTS_URL_PATH}/ref-app-example-1`, {
+      const response = await fetch(`${SERVER_URL}${PATH_CONSTANTS.DOCUMENTS_URL_PATH}/ref-app-example-1`, {
         headers: {
           Authorization: `Basic ${credentials}`,
         },
@@ -195,7 +190,7 @@ describe("Server Integration", () => {
 
     it("should handle malformed document names gracefully", async () => {
       const credentials = Buffer.from("admin:secret").toString("base64");
-      const response = await fetch(`${SERVER_URL}${ORD_DOCUMENTS_URL_PATH}/../../etc/passwd`, {
+      const response = await fetch(`${SERVER_URL}${PATH_CONSTANTS.DOCUMENTS_URL_PATH}/../../etc/passwd`, {
         headers: {
           Authorization: `Basic ${credentials}`,
         },
@@ -211,7 +206,7 @@ describe("Server Integration", () => {
     beforeAll(async () => {
       const options: ProviderServerOptions = {
         ordDirectory: LOCAL_DIRECTORY,
-        ordDocumentsSubDirectory: ORD_DOCUMENTS_SUB_DIRECTORY,
+        ordDocumentsSubDirectory: PATH_CONSTANTS.DOCUMENTS_SUBDIRECTORY,
         sourceType: OptSourceType.Local,
         host: TEST_HOST,
         port: MULTI_AUTH_PORT,
@@ -231,7 +226,7 @@ describe("Server Integration", () => {
 
     it("should accept basic auth when multiple auth methods are configured", async () => {
       const credentials = Buffer.from("admin:secret").toString("base64");
-      const response = await fetch(`${SERVER_URL_2}${ORD_DOCUMENTS_URL_PATH}/ref-app-example-1`, {
+      const response = await fetch(`${SERVER_URL_2}${PATH_CONSTANTS.DOCUMENTS_URL_PATH}/ref-app-example-1`, {
         headers: {
           Authorization: `Basic ${credentials}`,
         },
@@ -244,7 +239,7 @@ describe("Server Integration", () => {
   describe("Server Configuration", () => {
     it("should set correct content type headers", async () => {
       const credentials = Buffer.from("admin:secret").toString("base64");
-      const response = await fetch(`${SERVER_URL}${ORD_DOCUMENTS_URL_PATH}/ref-app-example-1`, {
+      const response = await fetch(`${SERVER_URL}${PATH_CONSTANTS.DOCUMENTS_URL_PATH}/ref-app-example-1`, {
         headers: {
           Authorization: `Basic ${credentials}`,
         },
@@ -263,7 +258,7 @@ describe("Server Integration", () => {
 
       const requests = Array(10)
         .fill(null)
-        .map(() => fetch(`${SERVER_URL}${ORD_DOCUMENTS_URL_PATH}/ref-app-example-1`, { headers }));
+        .map(() => fetch(`${SERVER_URL}${PATH_CONSTANTS.DOCUMENTS_URL_PATH}/ref-app-example-1`, { headers }));
 
       const responses = await Promise.all(requests);
       responses.forEach((response) => {
@@ -273,7 +268,7 @@ describe("Server Integration", () => {
 
     it("should return ETag headers for caching", async () => {
       const credentials = Buffer.from("admin:secret").toString("base64");
-      const response = await fetch(`${SERVER_URL}${ORD_DOCUMENTS_URL_PATH}/ref-app-example-1`, {
+      const response = await fetch(`${SERVER_URL}${PATH_CONSTANTS.DOCUMENTS_URL_PATH}/ref-app-example-1`, {
         headers: {
           Authorization: `Basic ${credentials}`,
         },

src/__tests__/server.integration.test.ts

@@ -9,6 +9,7 @@ import { log } from "src/util/logger.js";
 import { validateAndParseOptions } from "src/util/optsValidation.js";
 import { ValidationError } from "./model/error/ValidationError.js";
 import { showCleanHelp } from "./util/cliHelp.js";
+import { PATH_CONSTANTS } from "./constant.js";
 
 config();
 
@@ -30,12 +31,12 @@ program
   .option(
     "-d, --directory <directory>",
     'Directory containing ORD documents. Required when source-type is "local".',
-    process.env.ORD_DIRECTORY,
+    process.env.ORD_DIRECTORY || PATH_CONSTANTS.GITHUB_DEFAULT_ROOT,
   )
   .option(
     "--documents-subdirectory <subdirectory>",
     "Subdirectory name for ORD documents within the main directory (default: 'documents')",
-    process.env.ORD_DOCUMENTS_SUBDIRECTORY || "documents",
+    PATH_CONSTANTS.DOCUMENTS_SUBDIRECTORY,
   )
   .option(
     "-a, --auth <authTypes>",

src/cli.ts

@@ -1,8 +1,16 @@
-export const ORD_URL_PATH = "ord";
-export const ORD_VERSION = "v1";
-export const WELL_KNOWN_ENDPOINT = `/.well-known/open-resource-discovery`;
-export const ORD_SERVER_PREFIX_PATH = `/${ORD_URL_PATH}/${ORD_VERSION}`;
-export const ORD_DOCUMENTS_URL_PATH = `${ORD_SERVER_PREFIX_PATH}/documents`;
-export const ORD_DOCUMENTS_SUB_DIRECTORY = process.env.ORD_DOCUMENTS_SUBDIRECTORY || "documents";
-export const ORD_DOCUMENTS_GITHUB_DIRECTORY = "data/documents";
-export const ORD_GITHUB_DEFAULT_ROOT_DIRECTORY = "data";
+// URL path constants
+export const PATH_CONSTANTS = {
+  // Base paths
+  ORD_URL_PATH: "ord",
+  ORD_VERSION: "v1",
+  WELL_KNOWN_ENDPOINT: "/.well-known/open-resource-discovery",
+
+  // Derived paths
+  SERVER_PREFIX: `/ord/v1`,
+  DOCUMENTS_URL_PATH: `/ord/v1/documents`,
+
+  // Directory constants
+  DOCUMENTS_SUBDIRECTORY: process.env.ORD_DOCUMENTS_SUBDIRECTORY || "documents",
+  GITHUB_DEFAULT_ROOT: "data",
+  GITHUB_DOCUMENTS_PATH: "data/documents",
+};

src/constant.ts

@@ -0,0 +1,66 @@
+import { GithubOpts } from "../model/github.js";
+import { OptAuthMethod, OptSourceType } from "../model/cli.js";
+import { DocumentRepository } from "../repositories/interfaces/documentRepository.js";
+import { GithubDocumentRepository } from "../repositories/githubDocumentRepository.js";
+import { LocalDocumentRepository } from "../repositories/localDocumentRepository.js";
+import { CacheService } from "../services/cacheService.js";
+import { DocumentService } from "../services/documentService.js";
+import { DocumentRouter } from "../routes/documentRouter.js";
+import { FqnDocumentMap } from "../util/fqnHelpers.js";
+import { ProcessingContext } from "../services/interfaces/processingContext.js";
+import { PATH_CONSTANTS } from "../constant.js";
+
+interface FactoryOptions {
+  sourceType: OptSourceType;
+  baseUrl: string;
+  authMethods: OptAuthMethod[];
+  fqnDocumentMap: FqnDocumentMap;
+  documentsSubDirectory?: string;
+  githubOpts?: GithubOpts;
+  ordDirectory?: string;
+}
+
+export class RouterFactory {
+  public static async createRouter(options: FactoryOptions): Promise<DocumentRouter> {
+    const cacheService = new CacheService();
+
+    let repository: DocumentRepository;
+    let processingContext: ProcessingContext;
+    const documentsSubDirectory = options.documentsSubDirectory || PATH_CONSTANTS.DOCUMENTS_SUBDIRECTORY;
+
+    if (options.sourceType === OptSourceType.Github && options.githubOpts) {
+      repository = new GithubDocumentRepository(options.githubOpts);
+      processingContext = {
+        baseUrl: options.baseUrl,
+        authMethods: options.authMethods,
+        githubBranch: options.githubOpts.githubBranch,
+        githubApiUrl: options.githubOpts.githubApiUrl,
+        githubRepo: options.githubOpts.githubRepository,
+        githubToken: options.githubOpts.githubToken,
+      };
+    } else if (options.sourceType === OptSourceType.Local && options.ordDirectory) {
+      repository = new LocalDocumentRepository(options.ordDirectory);
+      processingContext = {
+        baseUrl: options.baseUrl,
+        authMethods: options.authMethods,
+      };
+    } else {
+      throw new Error("Invalid configuration: Missing required options for the specified source type.");
+    }
+
+    const documentService = new DocumentService(repository, cacheService, processingContext, documentsSubDirectory);
+
+    // Ensure FQN map is generated and retrieve it
+    // Calling getFqnMap also ensures ensureDataLoaded has run
+    const fqnDocumentMap = await documentService.getFqnMap();
+
+    const routerOptions = {
+      baseUrl: options.baseUrl,
+      authMethods: options.authMethods,
+      fqnDocumentMap: fqnDocumentMap,
+      documentsSubDirectory: documentsSubDirectory,
+    };
+
+    return new DocumentRouter(documentService, routerOptions);
+  }
+}