feat: add support for Websocket passthrough (#1172)

Author: remore

documentation/docs/websocket/createWebsocketHandoff.mdx

@@ -0,0 +1,53 @@
+---
+hide_title: false
+hide_table_of_contents: false
+pagination_next: null
+pagination_prev: null
+---
+
+# createWebsocketHandoff
+
+The **`createWebsocketHandoff()`** function creates a Response instance which informs Fastly to pass the original Request through Websocket, to the declared backend.
+
+## Syntax
+
+```js
+createWebsocketHandoff(request, backend)
+```
+
+### Parameters
+
+- `request` _: Request_
+  - The request to pass through Websocket.
+- `backend` _: string_
+  - The name of the backend that Websocket 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 Websocket.
+
+```js
+import { createWebsocketHandoff } from "fastly:websocket";
+
+async function handleRequest(event) {
+  try {
+    const url = new URL(event.request.url);
+    if (url.pathname === '/stream') {
+      return createWebsocketHandoff(event.request, 'websocket_backend');
+    } else {
+      return new Response('oopsie, make a request to /stream for some websocket goodies', { status: 404 });
+    }
+  } catch (error) {
+    console.error({error});
+    return new Response(error.message, {status:500})
+  }
+}
+
+addEventListener("fetch", (event) => event.respondWith(handleRequest(event)));
+```

documentation/rename-docs.mjs

@@ -20,6 +20,7 @@ const subsystems = [
   'env',
   'experimental',
   'fanout',
+  'websocket',
   'geolocation',
   'kv-store',
   'logger',

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

@@ -21,6 +21,7 @@ import './dictionary.js';
 import './edge-rate-limiter.js';
 import './env.js';
 import './fanout.js';
+import './websocket.js';
 import './fastly-global.js';
 import './fetch-errors.js';
 import './geoip.js';

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

@@ -0,0 +1,74 @@
+import { assert, assertDoesNotThrow, assertThrows } from './assertions.js';
+import { routes } from './routes.js';
+import { createWebsocketHandoff } from 'fastly:websocket';
+
+routes.set('/createWebsocketHandoff', () => {
+  assert(
+    typeof createWebsocketHandoff,
+    'function',
+    'typeof createWebsocketHandoff',
+  );
+
+  assert(
+    createWebsocketHandoff.name,
+    'createWebsocketHandoff',
+    'createWebsocketHandoff.name',
+  );
+
+  assert(createWebsocketHandoff.length, 2, 'createWebsocketHandoff.length');
+
+  assertDoesNotThrow(() => createWebsocketHandoff(new Request('.'), 'hello'));
+
+  assertThrows(() => createWebsocketHandoff());
+
+  assertThrows(() => createWebsocketHandoff(1, ''));
+
+  let result = createWebsocketHandoff(new Request('.'), 'hello');
+  assert(result instanceof Response, true, 'result instanceof Response');
+
+  assertThrows(
+    () => new createWebsocketHandoff(new Request('.'), 'hello'),
+    TypeError,
+  );
+
+  assertDoesNotThrow(() => {
+    createWebsocketHandoff.call(undefined, new Request('.'), '1');
+  });
+
+  // https://tc39.es/ecma262/#sec-tostring
+  let sentinel;
+  const test = () => {
+    sentinel = Symbol();
+    const key = {
+      toString() {
+        throw sentinel;
+      },
+    };
+    createWebsocketHandoff(new Request('.'), key);
+  };
+  assertThrows(test);
+  try {
+    test();
+  } catch (thrownError) {
+    assert(thrownError, sentinel, 'thrownError === sentinel');
+  }
+  assertThrows(
+    () => {
+      createWebsocketHandoff(new Request('.'), Symbol());
+    },
+    TypeError,
+    `can't convert symbol to string`,
+  );
+
+  assertThrows(
+    () => createWebsocketHandoff(new Request('.')),
+    TypeError,
+    `createWebsocketHandoff: At least 2 arguments required, but only 1 passed`,
+  );
+
+  assertThrows(
+    () => createWebsocketHandoff(new Request('.'), ''),
+    Error,
+    `createWebsocketHandoff: Backend parameter can not be an empty string`,
+  );
+});

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

@@ -1002,6 +1002,7 @@
     "environments": ["viceroy"]
   },
   "GET /createFanoutHandoff": {},
+  "GET /createWebsocketHandoff": {},
   "GET /fastly/now": {},
   "GET /fastly/version": {},
   "GET /fastly/getgeolocationforipaddress/interface": {

runtime/fastly/builtins/fastly.cpp

@@ -283,7 +283,73 @@ bool Fastly::createFanoutHandoff(JSContext *cx, unsigned argc, JS::Value *vp) {
 
   JS::RootedObject response(cx, Response::create(cx, response_instance, response_handle.unwrap(),
                                                  body_handle.unwrap(), is_upstream,
-                                                 grip_upgrade_request, backend_str));
+                                                 grip_upgrade_request, nullptr, backend_str));
+  if (!response) {
+    return false;
+  }
+
+  RequestOrResponse::set_url(response, RequestOrResponse::url(&request_value.toObject()));
+  args.rval().setObject(*response);
+
+  return true;
+}
+
+bool Fastly::createWebsocketHandoff(JSContext *cx, unsigned argc, JS::Value *vp) {
+  JS::CallArgs args = CallArgsFromVp(argc, vp);
+  REQUEST_HANDLER_ONLY("createWebsocketHandoff");
+  if (!args.requireAtLeast(cx, "createWebsocketHandoff", 2)) {
+    return false;
+  }
+
+  auto request_value = args.get(0);
+  if (!Request::is_instance(request_value)) {
+    JS_ReportErrorUTF8(cx,
+                       "createWebsocketHandoff: request parameter must be an instance of Request");
+    return false;
+  }
+  auto websocket_upgrade_request = &request_value.toObject();
+
+  auto response_handle = host_api::HttpResp::make();
+  if (auto *err = response_handle.to_err()) {
+    HANDLE_ERROR(cx, *err);
+    return false;
+  }
+  auto body_handle = host_api::HttpBody::make();
+  if (auto *err = body_handle.to_err()) {
+    HANDLE_ERROR(cx, *err);
+    return false;
+  }
+
+  JS::RootedObject response_instance(
+      cx, JS_NewObjectWithGivenProto(cx, &Response::class_, Response::proto_obj));
+  if (!response_instance) {
+    return false;
+  }
+
+  auto backend_value = args.get(1);
+  JS::RootedString backend_str(cx, JS::ToString(cx, backend_value));
+  if (!backend_str) {
+    return false;
+  }
+  auto backend_chars = core::encode(cx, backend_str);
+  if (!backend_chars) {
+    return false;
+  }
+  if (backend_chars.len == 0) {
+    JS_ReportErrorUTF8(cx, "createWebsocketHandoff: Backend parameter can not be an empty string");
+    return false;
+  }
+
+  if (backend_chars.len > 254) {
+    JS_ReportErrorUTF8(cx, "createWebsocketHandoff: name can not be more than 254 characters");
+    return false;
+  }
+
+  bool is_upstream = true;
+
+  JS::RootedObject response(cx, Response::create(cx, response_instance, response_handle.unwrap(),
+                                                 body_handle.unwrap(), is_upstream, nullptr,
+                                                 websocket_upgrade_request, backend_str));
   if (!response) {
     return false;
   }
@@ -547,6 +613,7 @@ bool install(api::Engine *engine) {
       JS_FN("getLogger", Fastly::getLogger, 1, JSPROP_ENUMERATE),
       JS_FN("includeBytes", Fastly::includeBytes, 1, JSPROP_ENUMERATE),
       JS_FN("createFanoutHandoff", Fastly::createFanoutHandoff, 2, JSPROP_ENUMERATE),
+      JS_FN("createWebsocketHandoff", Fastly::createWebsocketHandoff, 2, JSPROP_ENUMERATE),
       ENABLE_EXPERIMENTAL_HIGH_RESOLUTION_TIME_METHODS ? nowfn : end,
       end};
 
@@ -684,6 +751,21 @@ bool install(api::Engine *engine) {
   if (!engine->define_builtin_module("fastly:fanout", fanout_val)) {
     return false;
   }
+  // fastly:websocket
+  RootedObject websocket(engine->cx(), JS_NewObject(engine->cx(), nullptr));
+  RootedValue websocket_val(engine->cx(), JS::ObjectValue(*websocket));
+  RootedValue create_websocket_handoff_val(engine->cx());
+  if (!JS_GetProperty(engine->cx(), fastly, "createWebsocketHandoff",
+                      &create_websocket_handoff_val)) {
+    return false;
+  }
+  if (!JS_SetProperty(engine->cx(), websocket, "createWebsocketHandoff",
+                      create_websocket_handoff_val)) {
+    return false;
+  }
+  if (!engine->define_builtin_module("fastly:websocket", websocket_val)) {
+    return false;
+  }
 
   // debugMessages for debug-only builds
 #ifdef DEBUG

runtime/fastly/builtins/fastly.h

@@ -45,6 +45,7 @@ class Fastly : public builtins::BuiltinNoConstructor<Fastly> {
   static const JSPropertySpec properties[];
 
   static bool createFanoutHandoff(JSContext *cx, unsigned argc, JS::Value *vp);
+  static bool createWebsocketHandoff(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/fastly/builtins/fetch-event.cpp

@@ -679,6 +679,17 @@ bool response_promise_then_handler(JSContext *cx, JS::HandleObject event, JS::Ha
     return true;
   }
 
+  if (auto websocket_upgrade_request = Response::websocket_upgrade_request(response_obj)) {
+    auto backend = Response::backend_str(cx, response_obj);
+
+    auto res = websocket_upgrade_request->redirect_to_websocket_proxy(backend);
+    if (auto *err = res.to_err()) {
+      HANDLE_ERROR(cx, *err);
+      return false;
+    }
+    return true;
+  }
+
   bool streaming = false;
   if (!RequestOrResponse::maybe_stream_body(cx, response_obj, &streaming)) {
     return false;

runtime/fastly/builtins/fetch/request-response.cpp

@@ -2958,6 +2958,16 @@ std::optional<host_api::HttpReq> Response::grip_upgrade_request(JSObject *obj) {
   return host_api::HttpReq(grip_upgrade_request.toInt32());
 }
 
+std::optional<host_api::HttpReq> Response::websocket_upgrade_request(JSObject *obj) {
+  MOZ_ASSERT(is_instance(obj));
+  auto websocket_upgrade_request =
+      JS::GetReservedSlot(obj, static_cast<uint32_t>(Slots::WebsocketUpgradeRequest));
+  if (websocket_upgrade_request.isUndefined()) {
+    return std::nullopt;
+  }
+  return host_api::HttpReq(websocket_upgrade_request.toInt32());
+}
+
 host_api::HostString Response::backend_str(JSContext *cx, JSObject *obj) {
   MOZ_ASSERT(is_instance(obj));
 
@@ -3418,7 +3428,7 @@ bool Response::redirect(JSContext *cx, unsigned argc, JS::Value *vp) {
     return false;
   }
   JS::RootedObject response(
-      cx, create(cx, response_instance, response_handle, body, false, nullptr, nullptr));
+      cx, create(cx, response_instance, response_handle, body, false, nullptr, nullptr, nullptr));
   if (!response) {
     return false;
   }
@@ -3562,7 +3572,7 @@ bool Response::json(JSContext *cx, unsigned argc, JS::Value *vp) {
     return false;
   }
   JS::RootedObject response(
-      cx, create(cx, response_instance, response_handle, body, false, nullptr, nullptr));
+      cx, create(cx, response_instance, response_handle, body, false, nullptr, nullptr, nullptr));
   if (!response) {
     return false;
   }
@@ -4338,7 +4348,7 @@ 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, false, nullptr, nullptr));
+      cx, create(cx, responseInstance, response_handle, body, false, nullptr, nullptr, nullptr));
   if (!response) {
     return false;
   }
@@ -4511,7 +4521,7 @@ JSObject *Response::create(JSContext *cx, HandleObject request, host_api::Respon
   bool is_upstream = true;
   RootedString backend(cx, RequestOrResponse::backend(request));
   JS::RootedObject response(cx, Response::create(cx, response_instance, response_handle, body,
-                                                 is_upstream, nullptr, backend));
+                                                 is_upstream, nullptr, nullptr, backend));
   if (!response) {
     return nullptr;
   }
@@ -4540,7 +4550,7 @@ void Response::finalize(JS::GCContext *gcx, JSObject *self) {
 JSObject *Response::create(JSContext *cx, JS::HandleObject response,
                            host_api::HttpResp response_handle, host_api::HttpBody body_handle,
                            bool is_upstream, JSObject *grip_upgrade_request,
-                           JS::HandleString backend) {
+                           JSObject *websocket_upgrade_request, JS::HandleString backend) {
   JS::SetReservedSlot(response, static_cast<uint32_t>(Slots::Response),
                       JS::Int32Value(response_handle.handle));
   JS::SetReservedSlot(response, static_cast<uint32_t>(Slots::Headers), JS::NullValue());
@@ -4556,6 +4566,10 @@ JSObject *Response::create(JSContext *cx, JS::HandleObject response,
     JS::SetReservedSlot(response, static_cast<uint32_t>(Slots::GripUpgradeRequest),
                         JS::Int32Value(Request::request_handle(grip_upgrade_request).handle));
   }
+  if (websocket_upgrade_request) {
+    JS::SetReservedSlot(response, static_cast<uint32_t>(Slots::WebsocketUpgradeRequest),
+                        JS::Int32Value(Request::request_handle(websocket_upgrade_request).handle));
+  }
   JS::SetReservedSlot(response, static_cast<uint32_t>(Slots::StorageAction), JS::UndefinedValue());
   JS::SetReservedSlot(response, static_cast<uint32_t>(RequestOrResponse::Slots::CacheEntry),
                       JS::UndefinedValue());

runtime/fastly/builtins/fetch/request-response.h

@@ -264,6 +264,7 @@ class Response final : public builtins::FinalizableBuiltinImpl<Response> {
     StatusMessage,
     Redirected,
     GripUpgradeRequest,
+    WebsocketUpgradeRequest,
     StorageAction,
     SuggestedCacheWriteOptions,
     OverrideCacheWriteOptions,
@@ -291,7 +292,7 @@ class Response final : public builtins::FinalizableBuiltinImpl<Response> {
   static JSObject *create(JSContext *cx, JS::HandleObject response,
                           host_api::HttpResp response_handle, host_api::HttpBody body_handle,
                           bool is_upstream, JSObject *grip_upgrade_request,
-                          JS::HandleString backend);
+                          JSObject *websocket_upgrade_request, JS::HandleString backend);
 
   static host_api::HttpResp response_handle(JSObject *obj);
 
@@ -307,6 +308,7 @@ class Response final : public builtins::FinalizableBuiltinImpl<Response> {
 
   static bool is_upstream(JSObject *obj);
   static std::optional<host_api::HttpReq> grip_upgrade_request(JSObject *obj);
+  static std::optional<host_api::HttpReq> websocket_upgrade_request(JSObject *obj);
   static host_api::HostString backend_str(JSContext *cx, JSObject *obj);
   static uint16_t status(JSObject *obj);
   static JSString *status_message(JSObject *obj);

runtime/fastly/host-api/fastly.h

@@ -471,6 +471,10 @@ WASM_IMPORT("fastly_http_req", "redirect_to_grip_proxy_v2")
 int req_redirect_to_grip_proxy_v2(uint32_t req_handle, const char *backend_name,
                                   size_t backend_name_len);
 
+WASM_IMPORT("fastly_http_req", "redirect_to_websocket_proxy_v2")
+int req_redirect_to_websocket_proxy_v2(uint32_t req_handle, const char *backend_name,
+                                       size_t backend_name_len);
+
 /**
  * Set the cache override behavior for this request.
  *