feat: implement Fanout for JS SDK

Author: Jake Champion

.github/workflows/main.yml

@@ -230,6 +230,7 @@ jobs:
           - error
           - extend-from-builtins
           - extend-from-request
+          - fanout
           - geoip
           - hello-world
           - includeBytes
@@ -378,14 +379,15 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        fixture: 
+        fixture:
           - 'async-select'
           - 'byob'
           - 'byte-repeater'
           - 'cache-override'
           - 'crypto'
           - 'edge-dictionary'
           - 'error'
+          - 'fanout'
           - 'geoip'
           - 'hello-world'
           - 'multiple-set-cookie'

.vscode/c_cpp_properties.json

@@ -4,6 +4,7 @@
             "name": "sm-wasi",
             "includePath": [
                 "${workspaceFolder}/runtime/spidermonkey/debug/include",
+                "${workspaceFolder}/runtime/spidermonkey/release/include",
                 "/opt/wasi-sdk/share/wasi-sysroot/include/",
                 "${workspaceFolder}/runtime/js-compute-runtime",
                 "${workspaceFolder}/runtime/js-compute-runtime/build/openssl-3.0.7/include"
@@ -25,4 +26,4 @@
         }
     ],
     "version": 4
-}
+}

documentation/docs/fastly:fanout/createFanoutHandoff.mdx

@@ -0,0 +1,53 @@
+---
+hide_title: false
+hide_table_of_contents: false
+pagination_next: null
+pagination_prev: null
+---
+
+# createFanoutHandoff
+
+The **`createFanoutHandoff()`** function creates a Response instance which informs Fastly to pass the original Request through Fanout, to the declared backend.
+
+## Syntax
+
+```js
+createFanoutHandoff(request, backend)
+```
+
+### Parameters
+
+- `request` _: Request_
+  - The request to pass through Fanout.
+- `backend` _: string_
+  - The name of the backend that Fanout should send the request to.
+  - The name has to be between 1 and 254 characters inclusive.
+  - Throws a [`TypeError`](../../globals/TypeError/TypeError.mdx) if the value is not valid. I.E. The value is null, undefined, an empty string or a string with more than 254 characters.
+
+### Return value
+
+A Response instance is returned, which can then be used via `event.respondWith`.
+
+## Examples
+
+In this example application requests to the path `/stream` and sent handled via Fanout.
+
+```js
+import { createFanoutHandoff } from "fastly:fanout";
+
+async function handleRequest(event) {
+  try {
+    const url = new URL(event.request.url);
+    if (url.pathname === '/stream') {
+      return createFanoutHandoff(event.request, 'fanout');
+    } else {
+      return new Response('oopsie, make a request to /stream for some fanout goodies', { status: 404 });
+    }
+  } catch (error) {
+    console.error({error});
+    return new Response(error.message, {status:500})
+  }
+}
+
+addEventListener("fetch", (event) => event.respondWith(handleRequest(event)));
+```

integration-tests/js-compute/fixtures/fanout/bin/index.js

@@ -0,0 +1,74 @@
+/// <reference types="@fastly/js-compute" />
+/* eslint-env serviceworker */
+
+import { pass, assert, assertDoesNotThrow, assertThrows } from "../../../assertions.js";
+import { routes } from "../../../test-harness.js";
+import { createFanoutHandoff } from "fastly:fanout";
+
+let error;
+routes.set("/createFanoutHandoff", async () => {
+  error = assert(typeof createFanoutHandoff, "function", "typeof createFanoutHandoff");
+  if (error) { return error; }
+
+  error = assert(createFanoutHandoff.name, "createFanoutHandoff", "createFanoutHandoff.name");
+  if (error) { return error; }
+
+  error = assert(createFanoutHandoff.length, 2, "createFanoutHandoff.length");
+  if (error) { return error; }
+
+  error = assertDoesNotThrow(() => createFanoutHandoff(new Request('.'), 'hello'));
+  if (error) { return error; }
+
+  error = assertThrows(() => createFanoutHandoff());
+  if (error) { return error; }
+
+  error = assertThrows(() => createFanoutHandoff(1, ''));
+  if (error) { return error; }
+
+  let result = createFanoutHandoff(new Request('.'), 'hello');
+  error = assert(result instanceof Response, true, 'result instanceof Response');
+  if (error) { return error; }
+
+  error = assertThrows(() => new createFanoutHandoff(new Request('.'), 'hello'), TypeError, `createFanoutHandoff is not a constructor`)
+  if (error) { return error }
+
+  error = await assertDoesNotThrow(async () => {
+    createFanoutHandoff.call(undefined, new Request('.'), '1')
+  })
+  if (error) { return error }
+
+  // https://tc39.es/ecma262/#sec-tostring
+  // routes.set("/object-store/get/key-parameter-calls-7.1.17-ToString", async () => {
+  let sentinel;
+  const test = () => {
+    sentinel = Symbol();
+    const key = {
+      toString() {
+        throw sentinel;
+      }
+    }
+    createFanoutHandoff(new Request('.'), key)
+  }
+  error = assertThrows(test)
+  if (error) { return error }
+  try {
+    test()
+  } catch (thrownError) {
+    let error = assert(thrownError, sentinel, 'thrownError === sentinel')
+    if (error) { return error }
+  }
+  error = assertThrows(() => {
+    createFanoutHandoff(new Request('.'), Symbol())
+  }, TypeError, `can't convert symbol to string`)
+  if (error) { return error }
+
+  error = assertThrows(() => createFanoutHandoff(new Request('.')), TypeError, `createFanoutHandoff: At least 2 arguments required, but only 1 passed`)
+  if (error) { return error }
+
+  error = assertThrows(() => createFanoutHandoff(new Request('.'), ''), Error, `createFanoutHandoff: Backend parameter can not be an empty string`)
+  if (error) { return error }
+
+
+  return pass();
+});
+

integration-tests/js-compute/fixtures/fanout/fastly.toml.in

@@ -0,0 +1,12 @@
+# This file describes a Fastly Compute@Edge package. To learn more visit:
+# https://developer.fastly.com/reference/fastly-toml/
+
+authors = ["[email protected]"]
+description = ""
+language = "other"
+manifest_version = 2
+name = "fanout"
+service_id = ""
+
+[scripts]
+  build = "node ../../../../js-compute-runtime-cli.js"

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

@@ -0,0 +1,12 @@
+{
+  "GET /createFanoutHandoff": {
+    "environments": ["c@e", "viceroy"],
+    "downstream_request": {
+      "method": "GET",
+      "pathname": "/createFanoutHandoff"
+    },
+    "downstream_response": {
+      "status": 200
+    }
+  }
+}

runtime/js-compute-runtime/builtins/fastly.cpp

@@ -12,6 +12,7 @@
 #include "builtins/env.h"
 #include "builtins/fastly.h"
 #include "builtins/logger.h"
+#include "builtins/request-response.h"
 #include "builtins/shared/url.h"
 #include "core/geo_ip.h"
 #include "host_interface/host_call.h"
@@ -130,6 +131,69 @@ bool Fastly::includeBytes(JSContext *cx, unsigned argc, JS::Value *vp) {
   return true;
 }
 
+bool Fastly::createFanoutHandoff(JSContext *cx, unsigned argc, JS::Value *vp) {
+  JS::CallArgs args = CallArgsFromVp(argc, vp);
+  REQUEST_HANDLER_ONLY("createFanoutHandoff");
+  if (!args.requireAtLeast(cx, "createFanoutHandoff", 2)) {
+    return false;
+  }
+
+  auto request_value = args.get(0);
+  if (!Request::is_instance(request_value)) {
+    JS_ReportErrorUTF8(cx, "createFanoutHandoff: request parameter must be an instance of Request");
+    return false;
+  }
+
+  fastly_response_handle_t response_handle = INVALID_HANDLE;
+  fastly_error_t err;
+  if (!fastly_http_resp_new(&response_handle, &err)) {
+    HANDLE_ERROR(cx, err);
+    return false;
+  }
+  fastly_body_handle_t body_handle = INVALID_HANDLE;
+  if (!fastly_http_body_new(&body_handle, &err)) {
+    HANDLE_ERROR(cx, err);
+    return false;
+  }
+
+  JS::RootedObject response_instance(cx, JS_NewObjectWithGivenProto(cx, &builtins::Response::class_,
+                                                                    builtins::Response::proto_obj));
+  if (!response_instance) {
+    return false;
+  }
+
+  auto backend_value = args.get(1);
+  size_t length;
+  auto backend_chars = encode(cx, backend_value, &length);
+  if (!backend_chars) {
+    return false;
+  }
+  if (length == 0) {
+    JS_ReportErrorUTF8(cx, "createFanoutHandoff: Backend parameter can not be an empty string");
+    return false;
+  }
+
+  if (length > 254) {
+    JS_ReportErrorUTF8(cx, "createFanoutHandoff: name can not be more than 254 characters");
+    return false;
+  }
+
+  bool is_upstream = true;
+  bool is_grip_upgrade = true;
+  JS::RootedObject response(
+      cx, builtins::Response::create(cx, response_instance, response_handle, body_handle,
+                                     is_upstream, is_grip_upgrade, std::move(backend_chars)));
+  if (!response) {
+    return false;
+  }
+
+  builtins::RequestOrResponse::set_url(response,
+                                       builtins::RequestOrResponse::url(&request_value.toObject()));
+  args.rval().setObject(*response);
+
+  return true;
+}
+
 bool Fastly::now(JSContext *cx, unsigned argc, JS::Value *vp) {
   JS::CallArgs args = CallArgsFromVp(argc, vp);
   args.rval().setNumber(JS_Now());
@@ -228,6 +292,7 @@ bool Fastly::create(JSContext *cx, JS::HandleObject global, FastlyOptions option
       JS_FN("getGeolocationForIpAddress", getGeolocationForIpAddress, 1, JSPROP_ENUMERATE),
       JS_FN("getLogger", getLogger, 1, JSPROP_ENUMERATE),
       JS_FN("includeBytes", includeBytes, 1, JSPROP_ENUMERATE),
+      JS_FN("createFanoutHandoff", createFanoutHandoff, 2, JSPROP_ENUMERATE),
       options.getExperimentalHighResolutionTimeMethodsEnabled() ? nowfn : end,
       end};
 

runtime/js-compute-runtime/builtins/fastly.h

@@ -23,6 +23,7 @@ class Fastly : public BuiltinNoConstructor<Fastly> {
 
   static const JSPropertySpec properties[];
 
+  static bool createFanoutHandoff(JSContext *cx, unsigned argc, JS::Value *vp);
   static bool now(JSContext *cx, unsigned argc, JS::Value *vp);
   static bool dump(JSContext *cx, unsigned argc, JS::Value *vp);
   static bool enableDebugLogging(JSContext *cx, unsigned argc, JS::Value *vp);

runtime/js-compute-runtime/builtins/fetch-event.cpp

@@ -223,6 +223,20 @@ bool response_promise_then_handler(JSContext *cx, JS::HandleObject event, JS::Ha
   }
 
   bool streaming = false;
+  if (Response::is_grip_upgrade(response_obj)) {
+    std::string backend(Response::grip_backend(response_obj));
+    fastly_world_string_t backend_str;
+    backend_str.len = backend.length();
+    backend_str.ptr = backend.data();
+
+    fastly_error_t err;
+    if (!fastly_http_req_redirect_to_grip_proxy(&backend_str, &err)) {
+      HANDLE_ERROR(cx, err);
+      return false;
+    }
+    return true;
+  }
+
   if (!RequestOrResponse::maybe_stream_body(cx, response_obj, &streaming)) {
     return false;
   }

runtime/js-compute-runtime/builtins/request-response.cpp

@@ -17,7 +17,6 @@
 #include "js/JSON.h"
 #include "js/Stream.h"
 #include <algorithm>
-#include <iostream>
 #include <vector>
 
 #pragma clang diagnostic push
@@ -1978,6 +1977,20 @@ bool Response::is_upstream(JSObject *obj) {
   return JS::GetReservedSlot(obj, static_cast<uint32_t>(Slots::IsUpstream)).toBoolean();
 }
 
+bool Response::is_grip_upgrade(JSObject *obj) {
+  MOZ_ASSERT(is_instance(obj));
+  return JS::GetReservedSlot(obj, static_cast<uint32_t>(Slots::IsGripUpgrade)).toBoolean();
+}
+
+const char *Response::grip_backend(JSObject *obj) {
+  MOZ_ASSERT(is_instance(obj));
+
+  auto backend = reinterpret_cast<char *>(
+      JS::GetReservedSlot(obj, static_cast<uint32_t>(Slots::GripBackend)).toPrivate());
+  MOZ_ASSERT(backend);
+  return backend;
+}
+
 uint16_t Response::status(JSObject *obj) {
   MOZ_ASSERT(is_instance(obj));
   return (uint16_t)JS::GetReservedSlot(obj, static_cast<uint32_t>(Slots::Status)).toInt32();
@@ -2341,7 +2354,8 @@ bool Response::redirect(JSContext *cx, unsigned argc, JS::Value *vp) {
   if (!response_instance) {
     return false;
   }
-  JS::RootedObject response(cx, create(cx, response_instance, response_handle, body.handle, false));
+  JS::RootedObject response(
+      cx, create(cx, response_instance, response_handle, body.handle, false, false, nullptr));
   if (!response) {
     return false;
   }
@@ -2485,7 +2499,8 @@ bool Response::json(JSContext *cx, unsigned argc, JS::Value *vp) {
   if (!response_instance) {
     return false;
   }
-  JS::RootedObject response(cx, create(cx, response_instance, response_handle, body.handle, false));
+  JS::RootedObject response(
+      cx, create(cx, response_instance, response_handle, body.handle, false, false, nullptr));
   if (!response) {
     return false;
   }
@@ -2644,7 +2659,8 @@ bool Response::constructor(JSContext *cx, unsigned argc, JS::Value *vp) {
 
   auto body = make_res.unwrap();
   JS::RootedObject responseInstance(cx, JS_NewObjectForConstructor(cx, &class_, args));
-  JS::RootedObject response(cx, create(cx, responseInstance, response_handle, body.handle, false));
+  JS::RootedObject response(
+      cx, create(cx, responseInstance, response_handle, body.handle, false, false, nullptr));
   if (!response) {
     return false;
   }
@@ -2730,7 +2746,8 @@ bool Response::init_class(JSContext *cx, JS::HandleObject global) {
 
 JSObject *Response::create(JSContext *cx, JS::HandleObject response,
                            fastly_response_handle_t response_handle,
-                           fastly_body_handle_t body_handle, bool is_upstream) {
+                           fastly_body_handle_t body_handle, bool is_upstream, bool is_grip,
+                           JS::UniqueChars backend) {
   // MOZ_ASSERT(cx);
   // MOZ_ASSERT(is_instance(response));
   // MOZ_ASSERT(response_handle);
@@ -2745,6 +2762,8 @@ JSObject *Response::create(JSContext *cx, JS::HandleObject response,
   JS::SetReservedSlot(response, static_cast<uint32_t>(Slots::Redirected), JS::FalseValue());
   JS::SetReservedSlot(response, static_cast<uint32_t>(Slots::IsUpstream),
                       JS::BooleanValue(is_upstream));
+  JS::SetReservedSlot(response, static_cast<uint32_t>(Slots::IsGripUpgrade),
+                      JS::BooleanValue(is_grip));
 
   if (is_upstream) {
     uint16_t status = 0;
@@ -2761,7 +2780,8 @@ JSObject *Response::create(JSContext *cx, JS::HandleObject response,
       JS::SetReservedSlot(response, static_cast<uint32_t>(Slots::HasBody), JS::TrueValue());
     }
   }
-
+  JS::SetReservedSlot(response, static_cast<uint32_t>(Slots::GripBackend),
+                      JS::PrivateValue(std::move(backend.release())));
   return response;
 }