Improve OPTIONS responses across endpoints

enterprise/e2e/path/hurl/mcp-2025-11-25-lifecycle.all.hurl

@@ -244,8 +244,14 @@ header "X-Frame-Options" not exists
 header "Date" matches /^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), (0[1-9]|[12][0-9]|3[01]) (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) [0-9]{4} ([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9] GMT$/
 
 OPTIONS {{base}}/self/v1/mcp
-HTTP 404
+HTTP 204
 Cache-Control: no-store
+Access-Control-Allow-Origin: *
+Access-Control-Expose-Headers: Link, ETag
+Access-Control-Allow-Methods: GET, HEAD, OPTIONS
+Access-Control-Allow-Headers: Accept, Accept-Encoding, If-None-Match, If-Modified-Since
+Access-Control-Max-Age: 3600
+Allow: GET, HEAD, OPTIONS
 [Asserts]
 header "Vary" not exists
 header "Referrer-Policy" not exists

src/actions/action_default_v1.h

@@ -45,6 +45,12 @@ class ActionDefault_v1 : public sourcemeta::one::RouterAction {
   auto rest(const std::span<std::string_view>,
             sourcemeta::one::HTTPRequest &request,
             sourcemeta::one::HTTPResponse &response) -> void override {
+    if (request.method() == "options") {
+      sourcemeta::one::cors_preflight(request, response, "GET, HEAD, OPTIONS",
+                                      "Accept, Accept-Encoding, If-None-Match, "
+                                      "If-Modified-Since");
+      return;
+    }
     // Browser-targeted security headers we apply to every HTML response:
     //
     // - Referrer-Policy (W3C Referrer Policy):
@@ -91,7 +97,7 @@ class ActionDefault_v1 : public sourcemeta::one::RouterAction {
             request, response, sourcemeta::core::HTTP_STATUS_METHOD_NOT_ALLOWED,
             "sourcemeta:one/method-not-allowed",
             "This HTTP method is invalid for this URL", this->error_schema_,
-            "*", "GET, HEAD");
+            "*", "GET, HEAD, OPTIONS");
         return;
       }
       if (sourcemeta::core::http_match_accept(
@@ -180,7 +186,7 @@ class ActionDefault_v1 : public sourcemeta::one::RouterAction {
             request, response, sourcemeta::core::HTTP_STATUS_METHOD_NOT_ALLOWED,
             "sourcemeta:one/method-not-allowed",
             "This HTTP method is invalid for this URL", this->error_schema_,
-            "*", "GET, HEAD");
+            "*", "GET, HEAD, OPTIONS");
       } else {
         sourcemeta::one::json_error(
             request, response, sourcemeta::core::HTTP_STATUS_NOT_FOUND,

src/actions/action_dependency_tree_v1.h

@@ -55,6 +55,12 @@ class ActionDependencyTree_v1 : public sourcemeta::one::RouterAction {
   auto rest(const std::span<std::string_view> matches,
             sourcemeta::one::HTTPRequest &request,
             sourcemeta::one::HTTPResponse &response) -> void override {
+    if (request.method() == "options") {
+      sourcemeta::one::cors_preflight(request, response, "GET, HEAD, OPTIONS",
+                                      "Accept-Encoding, If-None-Match, "
+                                      "If-Modified-Since");
+      return;
+    }
     if (matches.empty()) {
       sourcemeta::one::json_error(
           request, response,

src/actions/action_health_check_v1.h

@@ -40,12 +40,17 @@ class ActionHealthCheck_v1 : public sourcemeta::one::RouterAction {
   auto rest(const std::span<std::string_view>,
             sourcemeta::one::HTTPRequest &request,
             sourcemeta::one::HTTPResponse &response) -> void override {
+    if (request.method() == "options") {
+      sourcemeta::one::cors_preflight(request, response, "GET, HEAD, OPTIONS",
+                                      "Accept, Accept-Encoding");
+      return;
+    }
     if (request.method() != "get" && request.method() != "head") {
       sourcemeta::one::json_error(
           request, response, sourcemeta::core::HTTP_STATUS_METHOD_NOT_ALLOWED,
           "sourcemeta:one/method-not-allowed",
           "This HTTP method is invalid for this URL", this->error_schema_, "*",
-          "GET, HEAD");
+          "GET, HEAD, OPTIONS");
       return;
     }
 

src/actions/action_jsonschema_serve_v1.h

@@ -85,6 +85,12 @@ class ActionJSONSchemaServe_v1 : public sourcemeta::one::RouterAction {
   auto rest(const std::span<std::string_view> matches,
             sourcemeta::one::HTTPRequest &request,
             sourcemeta::one::HTTPResponse &response) -> void override {
+    if (request.method() == "options") {
+      sourcemeta::one::cors_preflight(request, response, "GET, HEAD, OPTIONS",
+                                      "Accept, Accept-Encoding, If-None-Match, "
+                                      "If-Modified-Since");
+      return;
+    }
     serve(*this, matches.front(), request, response, this->error_schema_);
   }
 

src/actions/action_list_directory_v1.h

@@ -51,6 +51,12 @@ class ActionListDirectory_v1 : public sourcemeta::one::RouterAction {
   auto rest(const std::span<std::string_view> matches,
             sourcemeta::one::HTTPRequest &request,
             sourcemeta::one::HTTPResponse &response) -> void override {
+    if (request.method() == "options") {
+      sourcemeta::one::cors_preflight(request, response, "GET, HEAD, OPTIONS",
+                                      "Accept-Encoding, If-None-Match, "
+                                      "If-Modified-Since");
+      return;
+    }
     const std::string_view path_match{matches.empty() ? std::string_view{}
                                                       : matches.front()};
     const auto path{

src/actions/action_schema_search_v1.h

@@ -56,6 +56,11 @@ class ActionSchemaSearch_v1 : public sourcemeta::one::RouterAction {
   auto rest(const std::span<std::string_view>,
             sourcemeta::one::HTTPRequest &request,
             sourcemeta::one::HTTPResponse &response) -> void override {
+    if (request.method() == "options") {
+      sourcemeta::one::cors_preflight(request, response, "GET, HEAD, OPTIONS",
+                                      "Accept, Accept-Encoding");
+      return;
+    }
 
     // RFC 9110 §9.3.2: "The HEAD method is identical to GET except that the
     // server MUST NOT send content in the response. [...] The server SHOULD
@@ -67,7 +72,7 @@ class ActionSchemaSearch_v1 : public sourcemeta::one::RouterAction {
           request, response, sourcemeta::core::HTTP_STATUS_METHOD_NOT_ALLOWED,
           "sourcemeta:one/method-not-allowed",
           "This HTTP method is invalid for this URL", this->error_schema_, "*",
-          "GET, HEAD");
+          "GET, HEAD, OPTIONS");
       return;
     }
 

src/actions/action_serve_explorer_artifact_v1.h

@@ -50,6 +50,12 @@ class ActionServeExplorerArtifact_v1 : public sourcemeta::one::RouterAction {
   auto rest(const std::span<std::string_view> matches,
             sourcemeta::one::HTTPRequest &request,
             sourcemeta::one::HTTPResponse &response) -> void override {
+    if (request.method() == "options") {
+      sourcemeta::one::cors_preflight(request, response, "GET, HEAD, OPTIONS",
+                                      "Accept-Encoding, If-None-Match, "
+                                      "If-Modified-Since");
+      return;
+    }
     if (!matches.empty() &&
         (matches.front().find('#') != std::string_view::npos ||
          matches.front().find("%23") != std::string_view::npos)) {

src/actions/action_serve_schema_artifact_v1.h

@@ -51,6 +51,12 @@ class ActionServeSchemaArtifact_v1 : public sourcemeta::one::RouterAction {
   auto rest(const std::span<std::string_view> matches,
             sourcemeta::one::HTTPRequest &request,
             sourcemeta::one::HTTPResponse &response) -> void override {
+    if (request.method() == "options") {
+      sourcemeta::one::cors_preflight(request, response, "GET, HEAD, OPTIONS",
+                                      "Accept-Encoding, If-None-Match, "
+                                      "If-Modified-Since");
+      return;
+    }
     if (matches.empty()) {
       sourcemeta::one::json_error(
           request, response,

src/actions/action_serve_static_v1.h

@@ -42,13 +42,19 @@ class ActionServeStatic_v1 : public sourcemeta::one::RouterAction {
   auto rest(const std::span<std::string_view> matches,
             sourcemeta::one::HTTPRequest &request,
             sourcemeta::one::HTTPResponse &response) -> void override {
+    if (request.method() == "options") {
+      sourcemeta::one::cors_preflight(request, response, "GET, HEAD, OPTIONS",
+                                      "Accept-Encoding, If-None-Match, "
+                                      "If-Modified-Since");
+      return;
+    }
     if (this->file_root_.empty()) {
       if (request.method() != "get" && request.method() != "head") {
         sourcemeta::one::json_error(
             request, response, sourcemeta::core::HTTP_STATUS_METHOD_NOT_ALLOWED,
             "sourcemeta:one/method-not-allowed",
             "This HTTP method is invalid for this URL", this->error_schema_,
-            "*", "GET, HEAD");
+            "*", "GET, HEAD, OPTIONS");
         return;
       }
 

src/http/include/sourcemeta/one/http_helpers.h

@@ -52,6 +52,37 @@ inline auto send_response(const sourcemeta::core::HTTPStatus &status,
       std::format("{} {} {}", status.wire, request.method(), request.path()));
 }
 
+// RFC 9110 §9.3.7: OPTIONS responses describe communication options
+// for the target resource. Fetch §3.2.2 (CORS preflight): non-simple
+// cross-origin requests issue an OPTIONS preflight whose ACK shape
+// (status 204 + Access-Control-Allow-*) governs whether the actual
+// request fires. The per-surface `allow_methods` and `allow_headers`
+// are required so each action declares its own contract explicitly,
+// matching the K and L disciplines.
+// https://datatracker.ietf.org/doc/html/rfc9110#section-9.3.7
+// https://fetch.spec.whatwg.org/#cors-preflight-fetch
+inline auto cors_preflight(const HTTPRequest &request, HTTPResponse &response,
+                           const std::string_view allow_methods,
+                           const std::string_view allow_headers) -> void {
+  assert(!allow_methods.empty());
+  assert(!allow_headers.empty());
+  assert(allow_methods.find_first_of("\r\n") == std::string_view::npos);
+  assert(allow_headers.find_first_of("\r\n") == std::string_view::npos);
+  response.write_status(sourcemeta::core::HTTP_STATUS_NO_CONTENT);
+  response.write_header("Access-Control-Allow-Origin", "*");
+  response.write_header("Access-Control-Expose-Headers", "Link, ETag");
+  response.write_header("Access-Control-Allow-Methods", allow_methods);
+  response.write_header("Access-Control-Allow-Headers", allow_headers);
+  response.write_header("Access-Control-Max-Age", "3600");
+  // Browser preflight cache is governed by `Access-Control-Max-Age`;
+  // `no-store` keeps shared HTTP caches from storing this response.
+  response.write_header("Cache-Control", "no-store");
+  // RFC 9110 §9.3.7: OPTIONS responses SHOULD include Allow. Different
+  // audience than Access-Control-Allow-Methods (HTTP vs CORS preflight).
+  response.write_header("Allow", allow_methods);
+  send_response(sourcemeta::core::HTTP_STATUS_NO_CONTENT, request, response);
+}
+
 // CORS scope is required at every error site. No default for `origin` so a
 // caller cannot silently widen a restricted-origin handler to wildcard. An
 // empty origin means the route is CORS-disabled and no Allow-Origin or

src/router/artifact.cc

@@ -128,12 +128,19 @@ auto RouterAction::artifact_serve(
   // the default action is Accept-branched, others just gzip), so
   // the caller has to pick the right stack.
   assert(!vary.empty());
+  // OPTIONS preflight is a per-surface concern (the Allow-Headers axis
+  // varies by action), so each caller short-circuits it before reaching
+  // here via `cors_preflight`. If this assertion fires, a caller is
+  // missing that early branch and the 405 emitted below would advertise
+  // `Allow: GET, HEAD, OPTIONS` while simultaneously refusing OPTIONS,
+  // which is internally inconsistent.
+  assert(request.method() != "options");
   if (request.method() != "get" && request.method() != "head") {
     sourcemeta::one::json_error(
         request, response, sourcemeta::core::HTTP_STATUS_METHOD_NOT_ALLOWED,
         "sourcemeta:one/method-not-allowed",
         "This HTTP method is invalid for this URL", error_schema,
-        enable_cors ? "*" : "", "GET, HEAD");
+        enable_cors ? "*" : "", "GET, HEAD, OPTIONS");
     return;
   }
 

test/e2e/headless/hurl/explorer.all.hurl

@@ -24,7 +24,7 @@ Cache-Control: no-store
 Content-Type: application/problem+json
 Access-Control-Allow-Origin: *
 Access-Control-Expose-Headers: Link, ETag
-Allow: GET, HEAD
+Allow: GET, HEAD, OPTIONS
 Link: </self/v1/schemas/api/error>; rel="describedby"
 [Captures]
 last_response: body

test/e2e/headless/hurl/fetch.all.hurl

@@ -244,7 +244,7 @@ Cache-Control: no-store
 Content-Type: application/problem+json
 Access-Control-Allow-Origin: *
 Access-Control-Expose-Headers: Link, ETag
-Allow: GET, HEAD
+Allow: GET, HEAD, OPTIONS
 [Asserts]
 header "Vary" not exists
 header "Referrer-Policy" not exists
@@ -262,7 +262,7 @@ Cache-Control: no-store
 Content-Type: application/problem+json
 Access-Control-Allow-Origin: *
 Access-Control-Expose-Headers: Link, ETag
-Allow: GET, HEAD
+Allow: GET, HEAD, OPTIONS
 [Asserts]
 header "Vary" not exists
 header "Referrer-Policy" not exists
@@ -302,7 +302,7 @@ Cache-Control: no-store
 Content-Type: application/problem+json
 Access-Control-Allow-Origin: *
 Access-Control-Expose-Headers: Link, ETag
-Allow: GET, HEAD
+Allow: GET, HEAD, OPTIONS
 Link: </self/v1/schemas/api/error>; rel="describedby"
 [Captures]
 last_response_405: body

test/e2e/headless/hurl/health.all.hurl

@@ -31,7 +31,7 @@ Cache-Control: no-store
 Content-Type: application/problem+json
 Access-Control-Allow-Origin: *
 Access-Control-Expose-Headers: Link, ETag
-Allow: GET, HEAD
+Allow: GET, HEAD, OPTIONS
 [Asserts]
 header "Vary" not exists
 header "Referrer-Policy" not exists
@@ -48,7 +48,7 @@ Cache-Control: no-store
 Content-Type: application/problem+json
 Access-Control-Allow-Origin: *
 Access-Control-Expose-Headers: Link, ETag
-Allow: GET, HEAD
+Allow: GET, HEAD, OPTIONS
 [Asserts]
 header "Vary" not exists
 header "Referrer-Policy" not exists
@@ -65,7 +65,7 @@ Cache-Control: no-store
 Content-Type: application/problem+json
 Access-Control-Allow-Origin: *
 Access-Control-Expose-Headers: Link, ETag
-Allow: GET, HEAD
+Allow: GET, HEAD, OPTIONS
 [Asserts]
 header "Vary" not exists
 header "Referrer-Policy" not exists
@@ -82,7 +82,7 @@ Cache-Control: no-store
 Content-Type: application/problem+json
 Access-Control-Allow-Origin: *
 Access-Control-Expose-Headers: Link, ETag
-Allow: GET, HEAD
+Allow: GET, HEAD, OPTIONS
 [Asserts]
 header "Vary" not exists
 header "Referrer-Policy" not exists
@@ -94,18 +94,17 @@ jsonpath "$.type" == "sourcemeta:one/method-not-allowed"
 jsonpath "$.title" == "Method Not Allowed"
 
 OPTIONS {{base}}/self/v1/health
-HTTP 405
+HTTP 204
 Cache-Control: no-store
-Content-Type: application/problem+json
 Access-Control-Allow-Origin: *
 Access-Control-Expose-Headers: Link, ETag
-Allow: GET, HEAD
+Access-Control-Allow-Methods: GET, HEAD, OPTIONS
+Access-Control-Allow-Headers: Accept, Accept-Encoding
+Access-Control-Max-Age: 3600
+Allow: GET, HEAD, OPTIONS
 [Asserts]
 header "Vary" not exists
 header "Referrer-Policy" not exists
 header "Content-Security-Policy" not exists
 header "X-Frame-Options" not exists
 header "Date" matches /^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), (0[1-9]|[12][0-9]|3[01]) (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) [0-9]{4} ([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9] GMT$/
-jsonpath "$.status" == 405
-jsonpath "$.type" == "sourcemeta:one/method-not-allowed"
-jsonpath "$.title" == "Method Not Allowed"

test/e2e/headless/hurl/no-static.all.hurl

@@ -34,7 +34,7 @@ Cache-Control: no-store
 Content-Type: application/problem+json
 Access-Control-Allow-Origin: *
 Access-Control-Expose-Headers: Link, ETag
-Allow: GET, HEAD
+Allow: GET, HEAD, OPTIONS
 [Asserts]
 header "Vary" not exists
 header "Referrer-Policy" not exists
@@ -51,7 +51,7 @@ Cache-Control: no-store
 Content-Type: application/problem+json
 Access-Control-Allow-Origin: *
 Access-Control-Expose-Headers: Link, ETag
-Allow: GET, HEAD
+Allow: GET, HEAD, OPTIONS
 [Asserts]
 header "Vary" not exists
 header "Referrer-Policy" not exists
@@ -68,7 +68,7 @@ Cache-Control: no-store
 Content-Type: application/problem+json
 Access-Control-Allow-Origin: *
 Access-Control-Expose-Headers: Link, ETag
-Allow: GET, HEAD
+Allow: GET, HEAD, OPTIONS
 [Asserts]
 header "Vary" not exists
 header "Referrer-Policy" not exists

test/e2e/headless/hurl/not-found.all.hurl

@@ -69,4 +69,3 @@ header "Content-Security-Policy" not exists
 header "X-Frame-Options" not exists
 header "Date" matches /^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), (0[1-9]|[12][0-9]|3[01]) (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) [0-9]{4} ([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9] GMT$/
 jsonpath "$.valid" == true
-