fix: never error for missing client data, return null instead (#979)

Author: Guy Bedford

documentation/docs/globals/FetchEvent/FetchEvent.mdx

@@ -15,20 +15,22 @@ It provides the [`event.respondWith()`](./prototype/respondWith.mdx) method, whi
     - : The `Request` that was received by the application.
 - `FetchEvent.client` _**readonly**_
     - : Information about the downstream client that made the request.
+        While these fields are always defined on Compute, they may be *null* when not available in testing environments
+        such as Viceroy.
     - `FetchEvent.client.address` _**readonly**_
         - : A string representation of the IPv4 or IPv6 address of the downstream client.
     - `FetchEvent.client.geo` _**readonly**_
-        - : A [geolocation dictionary](../../fastly:geolocation/getGeolocationForIpAddress.mdx) corresponding to the IP address of the downstream client.
+        - : Either `null`, or a [geolocation dictionary](../../fastly:geolocation/getGeolocationForIpAddress.mdx) corresponding to the IP address of the downstream client.
     - `FetchEvent.client.tlsJA3MD5` _**readonly**_
-        - : A string representation of the JA3 hash of the TLS ClientHello message.
+        - : Either `null` or a string representation of the JA3 hash of the TLS ClientHello message.
     - `FetchEvent.client.tlsCipherOpensslName` _**readonly**_
-        - : A string representation of the cipher suite used to secure the client TLS connection.
+        - : Either `null` or a string representation of the cipher suite used to secure the client TLS connection.
     - `FetchEvent.client.tlsProtocol` _**readonly**_
-        - : A string representation of the TLS protocol version used to secure the client TLS connection.
+        - : Either `null` or a string representation of the TLS protocol version used to secure the client TLS connection.
     - `FetchEvent.client.tlsClientCertificate` _**readonly**_
-        - : An ArrayBuffer containing the raw client certificate in the mutual TLS handshake message. It is in PEM format. Returns an empty ArrayBuffer if this is not mTLS or available.
+        - : Either `null` or an ArrayBuffer containing the raw client certificate in the mutual TLS handshake message. It is in PEM format. Returns an empty ArrayBuffer if this is not mTLS or available.
     - `FetchEvent.client.tlsClientHello` _**readonly**_
-        - : An ArrayBuffer containing the raw bytes sent by the client in the TLS ClientHello message.
+        - : Either `null` or an ArrayBuffer containing the raw bytes sent by the client in the TLS ClientHello message.
 - `FetchEvent.server` _**readonly**_
     - : Information about the server receiving the request for the Fastly Compute service.
     - `FetchEvent.server.address` _**readonly**_

integration-tests/js-compute/fixtures/app/src/client.js

@@ -1,24 +1,32 @@
-import { assert } from './assertions.js';
+import { strictEqual } from './assertions.js';
 import { routes, isRunningLocally } from './routes.js';
 
 routes.set('/client/tlsJA3MD5', (event) => {
-  if (!isRunningLocally()) {
-    assert(
+  if (isRunningLocally()) {
+    strictEqual(event.client.tlsJA3MD5, null);
+  } else {
+    strictEqual(
       typeof event.client.tlsJA3MD5,
       'string',
       'typeof event.client.tlsJA3MD5',
     );
-    assert(event.client.tlsJA3MD5.length, 32, 'event.client.tlsJA3MD5.length');
+    strictEqual(
+      event.client.tlsJA3MD5.length,
+      32,
+      'event.client.tlsJA3MD5.length',
+    );
   }
 });
 routes.set('/client/tlsClientHello', (event) => {
-  if (!isRunningLocally()) {
-    assert(
+  if (isRunningLocally()) {
+    strictEqual(event.client.tlsClientHello, null);
+  } else {
+    strictEqual(
       event.client.tlsClientHello instanceof ArrayBuffer,
       true,
       'event.client.tlsClientHello instanceof ArrayBuffer',
     );
-    assert(
+    strictEqual(
       typeof event.client.tlsClientHello.byteLength,
       'number',
       'typeof event.client.tlsClientHello.byteLength',
@@ -27,13 +35,15 @@ routes.set('/client/tlsClientHello', (event) => {
 });
 
 routes.set('/client/tlsClientCertificate', (event) => {
-  if (!isRunningLocally()) {
-    assert(
+  if (isRunningLocally()) {
+    strictEqual(event.client.tlsClientCertificate, null);
+  } else {
+    strictEqual(
       event.client.tlsClientCertificate instanceof ArrayBuffer,
       true,
       'event.client.tlsClientCertificate instanceof ArrayBuffer',
     );
-    assert(
+    strictEqual(
       event.client.tlsClientCertificate.byteLength,
       0,
       'event.client.tlsClientCertificate.byteLength',
@@ -42,8 +52,10 @@ routes.set('/client/tlsClientCertificate', (event) => {
 });
 
 routes.set('/client/tlsCipherOpensslName', (event) => {
-  if (!isRunningLocally()) {
-    assert(
+  if (isRunningLocally()) {
+    strictEqual(event.client.tlsCipherOpensslName, null);
+  } else {
+    strictEqual(
       typeof event.client.tlsCipherOpensslName,
       'string',
       'typeof event.client.tlsCipherOpensslName',
@@ -52,8 +64,10 @@ routes.set('/client/tlsCipherOpensslName', (event) => {
 });
 
 routes.set('/client/tlsProtocol', (event) => {
-  if (!isRunningLocally()) {
-    assert(
+  if (isRunningLocally()) {
+    strictEqual(event.client.tlsProtocol, null);
+  } else {
+    strictEqual(
       typeof event.client.tlsProtocol,
       'string',
       'typeof event.client.tlsProtocol',

integration-tests/js-compute/fixtures/app/tests.json

@@ -308,41 +308,11 @@
   "GET /simple-cache/getOrSet/does-not-freeze-when-called-after-a-get": {
     "environments": ["compute"]
   },
-  "GET /client/tlsJA3MD5": {
-    "environments": ["compute"],
-    "downstream_response": {
-      "status": 200,
-      "body": "ok"
-    }
-  },
-  "GET /client/tlsClientHello": {
-    "environments": ["compute"],
-    "downstream_response": {
-      "status": 200,
-      "body": "ok"
-    }
-  },
-  "GET /client/tlsClientCertificate": {
-    "environments": ["compute"],
-    "downstream_response": {
-      "status": 200,
-      "body": "ok"
-    }
-  },
-  "GET /client/tlsCipherOpensslName": {
-    "environments": ["compute"],
-    "downstream_response": {
-      "status": 200,
-      "body": "ok"
-    }
-  },
-  "GET /client/tlsProtocol": {
-    "environments": ["compute"],
-    "downstream_response": {
-      "status": 200,
-      "body": "ok"
-    }
-  },
+  "GET /client/tlsJA3MD5": {},
+  "GET /client/tlsClientHello": {},
+  "GET /client/tlsClientCertificate": {},
+  "GET /client/tlsCipherOpensslName": {},
+  "GET /client/tlsProtocol": {},
   "GET /config-store": {},
   "GET /console": {
     "environments": ["viceroy"],

runtime/fastly/builtins/fetch-event.cpp

@@ -165,7 +165,12 @@ bool ClientInfo::tls_cipher_openssl_name_get(JSContext *cx, unsigned argc, JS::V
       return false;
     }
 
-    auto cipher = std::move(res.unwrap());
+    if (!res.unwrap().has_value()) {
+      args.rval().setNull();
+      return true;
+    }
+
+    auto cipher = std::move(res.unwrap().value());
     result.set(JS_NewStringCopyN(cx, cipher.ptr.get(), cipher.len));
     JS::SetReservedSlot(self, static_cast<uint32_t>(ClientInfo::Slots::Cipher),
                         JS::StringValue(result));
@@ -186,7 +191,12 @@ bool ClientInfo::tls_ja3_md5_get(JSContext *cx, unsigned argc, JS::Value *vp) {
       return false;
     }
 
-    auto ja3 = std::move(res.unwrap());
+    if (!res.unwrap().has_value()) {
+      args.rval().setNull();
+      return true;
+    }
+
+    auto ja3 = std::move(res.unwrap().value());
     JS::UniqueChars hex{OPENSSL_buf2hexstr(ja3.ptr.get(), ja3.len)};
     std::string ja3hex{hex.get(), std::remove(hex.get(), hex.get() + strlen(hex.get()), ':')};
 
@@ -209,7 +219,12 @@ bool ClientInfo::tls_client_hello_get(JSContext *cx, unsigned argc, JS::Value *v
       return false;
     }
 
-    auto hello = std::move(res.unwrap());
+    if (!res.unwrap().has_value()) {
+      args.rval().setNull();
+      return true;
+    }
+
+    auto hello = std::move(res.unwrap().value());
     buffer.set(JS::NewArrayBufferWithContents(cx, hello.len, hello.ptr.get(),
                                               JS::NewArrayBufferOutOfMemory::CallerMustFreeMemory));
     if (!buffer) {
@@ -238,7 +253,13 @@ bool ClientInfo::tls_client_certificate_get(JSContext *cx, unsigned argc, JS::Va
       HANDLE_ERROR(cx, *err);
       return false;
     }
-    auto cert = std::move(res.unwrap());
+
+    if (!res.unwrap().has_value()) {
+      args.rval().setNull();
+      return true;
+    }
+
+    auto cert = std::move(res.unwrap().value());
 
     buffer.set(JS::NewArrayBufferWithContents(cx, cert.len, cert.ptr.get(),
                                               JS::NewArrayBufferOutOfMemory::CallerMustFreeMemory));
@@ -269,7 +290,12 @@ bool ClientInfo::tls_protocol_get(JSContext *cx, unsigned argc, JS::Value *vp) {
       return false;
     }
 
-    auto protocol = std::move(res.unwrap());
+    if (!res.unwrap().has_value()) {
+      args.rval().setNull();
+      return true;
+    }
+
+    auto protocol = std::move(res.unwrap().value());
     result.set(JS_NewStringCopyN(cx, protocol.ptr.get(), protocol.len));
     JS::SetReservedSlot(self, static_cast<uint32_t>(ClientInfo::Slots::Protocol),
                         JS::StringValue(result));

runtime/fastly/host-api/host_api.cpp

@@ -1261,8 +1261,8 @@ Result<HostBytes> HttpReq::downstream_server_ip_addr() {
 }
 
 // http-req-downstream-tls-cipher-openssl-name: func() -> result<string, error>
-Result<HostString> HttpReq::http_req_downstream_tls_cipher_openssl_name() {
-  Result<HostString> res;
+Result<std::optional<HostString>> HttpReq::http_req_downstream_tls_cipher_openssl_name() {
+  Result<std::optional<HostString>> res;
 
   fastly::fastly_host_error err;
   fastly::fastly_world_string ret;
@@ -1278,7 +1278,11 @@ Result<HostString> HttpReq::http_req_downstream_tls_cipher_openssl_name() {
 
   if (!convert_result(status, &err)) {
     cabi_free(ret.ptr);
-    res.emplace_err(err);
+    if (error_is_optional_none(err)) {
+      res.emplace(std::nullopt);
+    } else {
+      res.emplace_err(err);
+    }
   } else {
     res.emplace(make_host_string(ret));
   }
@@ -1287,8 +1291,8 @@ Result<HostString> HttpReq::http_req_downstream_tls_cipher_openssl_name() {
 }
 
 // http-req-downstream-tls-protocol: func() -> result<string, error>
-Result<HostString> HttpReq::http_req_downstream_tls_protocol() {
-  Result<HostString> res;
+Result<std::optional<HostString>> HttpReq::http_req_downstream_tls_protocol() {
+  Result<std::optional<HostString>> res;
 
   fastly::fastly_host_error err;
   fastly::fastly_world_string ret;
@@ -1303,7 +1307,11 @@ Result<HostString> HttpReq::http_req_downstream_tls_protocol() {
   }
   if (!convert_result(status, &err)) {
     cabi_free(ret.ptr);
-    res.emplace_err(err);
+    if (error_is_optional_none(err)) {
+      res.emplace(std::nullopt);
+    } else {
+      res.emplace_err(err);
+    }
   } else {
     res.emplace(make_host_string(ret));
   }
@@ -1312,8 +1320,8 @@ Result<HostString> HttpReq::http_req_downstream_tls_protocol() {
 }
 
 // http-req-downstream-tls-client-hello: func() -> result<list<u8>, error>
-Result<HostBytes> HttpReq::http_req_downstream_tls_client_hello() {
-  Result<HostBytes> res;
+Result<std::optional<HostBytes>> HttpReq::http_req_downstream_tls_client_hello() {
+  Result<std::optional<HostBytes>> res;
 
   fastly::fastly_world_list_u8 ret;
   fastly::fastly_host_error err;
@@ -1327,7 +1335,11 @@ Result<HostBytes> HttpReq::http_req_downstream_tls_client_hello() {
 
   if (!convert_result(status, &err)) {
     cabi_free(ret.ptr);
-    res.emplace_err(err);
+    if (error_is_optional_none(err)) {
+      res.emplace(std::nullopt);
+    } else {
+      res.emplace_err(err);
+    }
   } else {
     res.emplace(make_host_bytes(ret));
   }
@@ -1336,8 +1348,8 @@ Result<HostBytes> HttpReq::http_req_downstream_tls_client_hello() {
 }
 
 // http-req-downstream-tls-raw-client-certificate: func() -> result<list<u8>, error>
-Result<HostBytes> HttpReq::http_req_downstream_tls_raw_client_certificate() {
-  Result<HostBytes> res;
+Result<std::optional<HostBytes>> HttpReq::http_req_downstream_tls_raw_client_certificate() {
+  Result<std::optional<HostBytes>> res;
 
   fastly::fastly_world_list_u8 ret;
   fastly::fastly_host_error err;
@@ -1350,7 +1362,11 @@ Result<HostBytes> HttpReq::http_req_downstream_tls_raw_client_certificate() {
   }
   if (!convert_result(status, &err)) {
     cabi_free(ret.ptr);
-    res.emplace_err(err);
+    if (error_is_optional_none(err)) {
+      res.emplace(std::nullopt);
+    } else {
+      res.emplace_err(err);
+    }
   } else {
     res.emplace(make_host_bytes(ret));
   }
@@ -1359,8 +1375,8 @@ Result<HostBytes> HttpReq::http_req_downstream_tls_raw_client_certificate() {
 }
 
 // http-req-downstream-tls-ja3-md5: func() -> result<list<u8>, error>
-Result<HostBytes> HttpReq::http_req_downstream_tls_ja3_md5() {
-  Result<HostBytes> res;
+Result<std::optional<HostBytes>> HttpReq::http_req_downstream_tls_ja3_md5() {
+  Result<std::optional<HostBytes>> res;
 
   fastly::fastly_world_list_u8 ret;
   fastly::fastly_host_error err;
@@ -1373,7 +1389,11 @@ Result<HostBytes> HttpReq::http_req_downstream_tls_ja3_md5() {
   }
   if (!convert_result(status, &err)) {
     cabi_free(ret.ptr);
-    res.emplace_err(err);
+    if (error_is_optional_none(err)) {
+      res.emplace(std::nullopt);
+    } else {
+      res.emplace_err(err);
+    }
   } else {
     res.emplace(make_host_bytes(ret));
   }

runtime/fastly/host-api/host_api_fastly.h

@@ -402,15 +402,15 @@ class HttpReq final : public HttpBase {
 
   static Result<HostBytes> downstream_server_ip_addr();
 
-  static Result<HostString> http_req_downstream_tls_cipher_openssl_name();
+  static Result<std::optional<HostString>> http_req_downstream_tls_cipher_openssl_name();
 
-  static Result<HostString> http_req_downstream_tls_protocol();
+  static Result<std::optional<HostString>> http_req_downstream_tls_protocol();
 
-  static Result<HostBytes> http_req_downstream_tls_client_hello();
+  static Result<std::optional<HostBytes>> http_req_downstream_tls_client_hello();
 
-  static Result<HostBytes> http_req_downstream_tls_raw_client_certificate();
+  static Result<std::optional<HostBytes>> http_req_downstream_tls_raw_client_certificate();
 
-  static Result<HostBytes> http_req_downstream_tls_ja3_md5();
+  static Result<std::optional<HostBytes>> http_req_downstream_tls_ja3_md5();
 
   Result<Void> auto_decompress_gzip();
 

test-d/globals.test-d.ts

@@ -208,11 +208,11 @@ import { expectError, expectType } from 'tsd';
   const client = {} as ClientInfo
   expectType<string>(client.address)
   expectType<Geolocation | null>(client.geo)
-  expectType<string>(client.tlsJA3MD5)
-  expectType<string>(client.tlsCipherOpensslName)
-  expectType<string>(client.tlsProtocol)
-  expectType<ArrayBuffer>(client.tlsClientCertificate)
-  expectType<ArrayBuffer>(client.tlsClientHello)
+  expectType<string | null>(client.tlsJA3MD5)
+  expectType<string | null>(client.tlsCipherOpensslName)
+  expectType<string | null>(client.tlsProtocol)
+  expectType<ArrayBuffer | null>(client.tlsClientCertificate)
+  expectType<ArrayBuffer | null>(client.tlsClientHello)
   // They are readonly properties
   expectError(client.address = '')
   expectError(client.geo = {} as Geolocation)