Introduce a new api configuration property (#850)

Signed-off-by: Juan Cruz Viotti <jv@jviotti.com>

Author: jviotti

.github/workflows/ci.yml

@@ -53,6 +53,11 @@ jobs:
         with:
           path: test/e2e/html
           edition: ${{ matrix.edition.name }}
+      - name: E2E (no-api)
+        uses: ./.github/actions/e2e
+        with:
+          path: test/e2e/no-api
+          edition: ${{ matrix.edition.name }}
       - name: E2E (chaos)
         uses: ./.github/actions/e2e
         with:

Makefile

@@ -75,6 +75,7 @@ docker: docker-build
 	$(MAKE) -C test/e2e/empty EDITION=$(EDITION)
 	$(MAKE) -C test/e2e/headless EDITION=$(EDITION)
 	$(MAKE) -C test/e2e/html EDITION=$(EDITION)
+	$(MAKE) -C test/e2e/no-api EDITION=$(EDITION)
 	$(MAKE) -C test/e2e/chaos EDITION=$(EDITION)
 ifeq ($(ENTERPRISE),ON)
 	$(MAKE) -C enterprise/e2e/html EDITION=$(EDITION)

collections/self/v1/schemas/configuration/configuration.json

@@ -16,6 +16,10 @@
     "contents": {
       "$ref": "./contents.json"
     },
+    "api": {
+      "type": [ "object", "boolean" ],
+      "additionalProperties": false
+    },
     "html": {
       "type": [ "object", "boolean" ],
       "properties": {
@@ -58,5 +62,24 @@
       "format": "uri"
     }
   },
-  "additionalProperties": false
+  "additionalProperties": false,
+  "dependentSchemas": {
+    "api": {
+      "if": {
+        "properties": {
+          "api": {
+            "const": false
+          }
+        }
+      },
+      "then": {
+        "required": [ "html" ],
+        "properties": {
+          "html": {
+            "const": false
+          }
+        }
+      }
+    }
+  }
 }

collections/self/v1/tests/configuration/configuration.test.json

@@ -152,6 +152,91 @@
           }
         }
       }
+    },
+    {
+      "description": "API as empty object with HTML enabled",
+      "valid": true,
+      "data": {
+        "url": "http://localhost:8000",
+        "api": {},
+        "html": {
+          "name": "Title",
+          "description": "Description"
+        },
+        "contents": {
+          "test": {
+            "title": "A sample schema folder",
+            "description": "For testing purposes",
+            "github": "sourcemeta/one"
+          }
+        }
+      }
+    },
+    {
+      "description": "API as true with HTML enabled",
+      "valid": true,
+      "data": {
+        "url": "http://localhost:8000",
+        "api": true,
+        "html": {
+          "name": "Title",
+          "description": "Description"
+        },
+        "contents": {
+          "test": {
+            "title": "A sample schema folder",
+            "description": "For testing purposes",
+            "github": "sourcemeta/one"
+          }
+        }
+      }
+    },
+    {
+      "description": "API explicitly false with HTML explicitly false",
+      "valid": true,
+      "data": {
+        "url": "http://localhost:8000",
+        "api": false,
+        "html": false
+      }
+    },
+    {
+      "description": "API as empty object with HTML explicitly false",
+      "valid": true,
+      "data": {
+        "url": "http://localhost:8000",
+        "api": {},
+        "html": false
+      }
+    },
+    {
+      "description": "API as true with HTML explicitly false",
+      "valid": true,
+      "data": {
+        "url": "http://localhost:8000",
+        "api": true,
+        "html": false
+      }
+    },
+    {
+      "description": "API false with HTML as object is invalid",
+      "valid": false,
+      "data": {
+        "url": "http://localhost:8000",
+        "api": false,
+        "html": {
+          "name": "Title",
+          "description": "Description"
+        }
+      }
+    },
+    {
+      "description": "API false without HTML set is invalid",
+      "valid": false,
+      "data": {
+        "url": "http://localhost:8000",
+        "api": false
+      }
     }
   ]
 }

docs/api.md

@@ -7,8 +7,9 @@ hide:
 
 !!! info
 
-    The HTTP API and the JSON Schemas that describe it (mounted at
-    `/self/v1/schemas`) are always available on every Sourcemeta One instance.
+    The HTTP API is enabled by default on every Sourcemeta One instance.
+    It can be disabled by setting `api` to `false` in the
+    [configuration file](configuration.md#api).
 
 This API has been architected with performance as a primary consideration,
 ensuring fast response times and efficient resource utilization across all

docs/configuration.md

@@ -64,7 +64,8 @@ structuring your instance.
 | `/url`          | String  | :red_circle: **Yes** | N/A | The absolute URL on which the instance will be served. Sourcemeta One will automatically add URI identifiers relative to this URL for every ingested schema. The absolute URL _may_ have a path component |
 | `/extends`      | Array   | No  | None | One or more configuration files to extend from. See the [Extends](#extends) section for more information |
 | `/contents`     | Object  | No  | None | The top-level [Collections](#collections) and [Pages](#pages) that compose the instance |
-| `/html`        | Object or Boolean  | No  | `{}` | Settings for the HTML explorer. If set to `false`, the instance runs in headless mode. See the [HTML](#html) section for more details |
+| `/html`        | Object or Boolean  | No  | `{}` | Settings for the HTML explorer. If set to `false`, the instance runs in headless mode. Enabling the HTML explorer implies the API must also be enabled. See the [HTML](#html) section for more details |
+| `/api`         | Object or Boolean  | No  | `{}` | Controls whether the HTTP API is accessible. If set to `false`, the JSON API is disabled. Can only be set to `false` when `/html` is also set to `false` |
 
 For example, a minimal configuration that mounts a single schema collection
 (`./schemas`) at URL `https://schemas.example.com/my-first-collection` may look

src/configuration/include/sourcemeta/one/configuration.h

@@ -48,6 +48,7 @@ struct Configuration {
   };
 
   std::optional<HTML> html;
+  bool api{true};
 
   struct Page {
     std::optional<sourcemeta::core::JSON::String> title;

src/configuration/parse.cc

@@ -127,6 +127,12 @@ auto Configuration::parse(const sourcemeta::core::JSON &data,
     }
   }
 
+  if (data.defines("api")) {
+    if (data.at("api").is_boolean() && !data.at("api").to_boolean()) {
+      result.api = false;
+    }
+  }
+
   entries_from_json(result.entries, "", data, default_base_path);
 
   return result;

src/configuration/read.cc

@@ -170,19 +170,28 @@ auto Configuration::read(const std::filesystem::path &configuration_path,
         sourcemeta::core::JSON{"The next-generation JSON Schema platform"});
   }
 
-  const auto self_path{std::filesystem::weakly_canonical(
-      collections_path / "self" / "v1" / "one.json")};
+  if (data.is_object() && data.defines("api") && data.at("api").is_boolean() &&
+      data.at("api").to_boolean()) {
+    data.at("api").into_object();
+  } else if (!data.defines("api")) {
+    data.assign("api", sourcemeta::core::JSON::make_object());
+  }
+
   if (!data.defines("extends")) {
     data.assign("extends", sourcemeta::core::JSON::make_array());
   }
 
-  auto extends_copy{sourcemeta::core::JSON::make_array()};
-  extends_copy.push_back(sourcemeta::core::JSON{self_path.string()});
-  for (const auto &entry : data.at("extends").as_array()) {
-    extends_copy.push_back(entry);
-  }
+  if (!(data.at("api").is_boolean() && !data.at("api").to_boolean())) {
+    const auto self_path{std::filesystem::weakly_canonical(
+        collections_path / "self" / "v1" / "one.json")};
+    auto extends_copy{sourcemeta::core::JSON::make_array()};
+    extends_copy.push_back(sourcemeta::core::JSON{self_path.string()});
+    for (const auto &entry : data.at("extends").as_array()) {
+      extends_copy.push_back(entry);
+    }
 
-  data.assign("extends", std::move(extends_copy));
+    data.assign("extends", std::move(extends_copy));
+  }
 
   const auto canonical_config{
       std::filesystem::weakly_canonical(configuration_path).native()};