miniflare

Minor Changes

• #5240 1720f0a Thanks @CarmenPopoviciu! - chore: bump workerd to 1.20240314.0

Patch Changes

• #5247 2e50d51 Thanks @CarmenPopoviciu! - fix: Add internal APIs to support the Workers Vitest integration

Patch Changes

• #5201 1235d48 Thanks @wydengyre! - fix: ensure miniflare works with Node 21.7.0+

• #5191 27fb22b Thanks @mrbbot! - fix: ensure redirect responses handled correctly with dispatchFetch()

  Previously, if your Worker returned a redirect response, calling dispatchFetch(url) would send another request to the original url rather than the redirect. This change ensures redirects are followed correctly.

  • If your Worker returns a relative redirect or an absolute redirect with the same origin as the original url, the request will be sent to the Worker.
  • If your Worker instead returns an absolute redirect with a different origin, the request will be sent to the Internet.
  • If a redirected request to a different origin returns an absolute redirect with the same origin as the original url, the request will also be sent to the Worker.

Minor Changes

• #5148 11951f3 Thanks @dom96! - chore: bump workerd to 1.20240304.0

• #5148 11951f3 Thanks @dom96! - fix: use python_workers compat flag for Python

Patch Changes

• #5133 42bcc72 Thanks @mrbbot! - fix: ensure internals can access workerd when starting on non-local host

  Previously, if Miniflare was configured to start on a host that wasn't 127.0.0.1, ::1, *, ::, or 0.0.0.0, calls to Miniflare API methods relying on the magic proxy (e.g. getKVNamespace(), getWorker(), etc.) would fail. This change ensures workerd is always accessible to Miniflare's internals. This also fixes wrangler dev when using local network address such as 192.168.0.10 with the --ip flag.

• #5133 42bcc72 Thanks @mrbbot! - fix: ensure IPv6 addresses can be used as hosts

  Previously, if Miniflare was configured to start on an IPv6 host, it could crash. This change ensures IPv6 addresses are handled correctly. This also fixes wrangler dev when using IPv6 addresses such as ::1 with the --ip flag.

Minor Changes

• #5081 0c0949d Thanks @garrettgu10! - chore: bump workerd to 1.20240223.1

Minor Changes

• #5068 b03db864 Thanks @mrbbot! - chore: bump workerd to 1.20240208.0

Minor Changes

• #4795 027f9719 Thanks @mrbbot! - feat: pass Miniflare instance as argument to custom service binding handlers

  This change adds a new Miniflare-typed parameter to function-valued service binding handlers. This provides easy access to the correct bindings when re-using service functions across instances.

  <!--prettier-ignore-start-->

  import assert from "node:assert";
  import { Miniflare, Response } from "miniflare";
  
  const mf = new Miniflare({
    serviceBindings: {
      SERVICE(request, instance) {
        assert(instance === mf);
        return new Response();
      },
    },
  });
  

  <!--prettier-ignore-end-->

• #4795 027f9719 Thanks @mrbbot! - feat: allow URLs to be passed in hyperdrives

  Previously, the hyperdrives option only accepted strings as connection strings. This change allows URL objects to be passed too.

• #4795 027f9719 Thanks @mrbbot! - feat: add support for custom root paths

  Miniflare has lots of file-path-valued options (e.g. scriptPath, kvPersist, textBlobBindings). Previously, these were always resolved relative to the current working directory before being used. This change adds a new rootPath shared, and per-worker option for customising this behaviour. Instead of resolving relative to the current working directory, Miniflare will now resolve path-valued options relative to the closest rootPath option. Paths are still resolved relative to the current working directory if no rootPaths are defined. Worker-level rootPaths are themselves resolved relative to the shared rootPath if defined.

  <!--prettier-ignore-start-->

  import { Miniflare } from "miniflare";
  
  const mf1 = new Miniflare({
    scriptPath: "index.mjs",
  });
  
  const mf2 = new Miniflare({
    rootPath: "a/b",
    scriptPath: "c/index.mjs",
  });
  
  const mf3 = new Miniflare({
    rootPath: "/a/b",
    workers: [
      {
        name: "1",
        rootPath: "c",
        scriptPath: "index.mjs",
      },
      {
        name: "2",
        scriptPath: "index.mjs",
      },
    ],
  });
  

  <!--prettier-ignore-end-->

• #4795 027f9719 Thanks @mrbbot! - feat: allow easy binding to current worker

  Previously, if you wanted to create a service binding to the current Worker, you'd need to know the Worker's name. This is usually possible, but can get tricky when dealing with many Workers. This change adds a new kCurrentWorker symbol that can be used instead of a Worker name in serviceBindings. kCurrentWorker always points to the Worker with the binding.

  <!--prettier-ignore-start-->

  import { kCurrentWorker, Miniflare } from "miniflare";
  
  const mf = new Miniflare({
    serviceBindings: {
      SELF: kCurrentWorker,
    },
    modules: true,
    script: `export default {
      fetch(request, env, ctx) {
        const { pathname } = new URL(request.url);
        if (pathname === "/recurse") {
          return env.SELF.fetch("http://placeholder");
        }
        return new Response("body");
      }
    }`,
  });
  
  const response = await mf.dispatchFetch("http://placeholder/recurse");
  console.log(await response.text()); // body
  

  <!--prettier-ignore-end-->

Patch Changes

• #4954 7723ac17 Thanks @mrbbot! - fix: allow relative scriptPath/modulesRoots to break out of current working directory

  Previously, Miniflare would resolve relative scriptPaths against moduleRoot multiple times resulting in incorrect paths and module names. This would lead to can't use ".." to break out of starting directory workerd errors. This change ensures Miniflare uses scriptPath as is, and only resolves it relative to modulesRoot when computing module names. Note this bug didn't affect service workers. This allows you to reference a modules scriptPath outside the working directory with something like:

  const mf = new Miniflare({
    modules: true,
    modulesRoot: "..",
    scriptPath: "../worker.mjs",
  });
  

  Fixes #4721

• #4795 027f9719 Thanks @mrbbot! - fix: return non-WebSocket responses for failed WebSocket upgrading fetch()es

  Previously, Miniflare's fetch() would throw an error if the Upgrade: websocket header was set, and a non-WebSocket response was returned from the origin. This change ensures the non-WebSocket response is returned from fetch() instead, with webSocket set to null. This allows the caller to handle the response as they see fit.

• #4795 027f9719 Thanks @mrbbot! - fix: ensure MiniflareOptions, WorkerOptions, and SharedOptions types are correct

  Miniflare uses Zod for validating options. Previously, Miniflare inferred *Options from the output types of its Zod schemas, rather than the input types. In most cases, these were the same. However, the hyperdrives option has different input/output types, preventing these from being type checked correctly.

Patch Changes

• #4950 05360e43 Thanks @petebacondarwin! - fix: ensure we do not rewrite external Origin headers in wrangler dev

  In https://github.com/cloudflare/workers-sdk/pull/4812 we tried to fix the Origin headers to match the Host header but were overzealous and rewrote Origin headers for external origins (outside of the proxy server's origin).

  This is now fixed, and moreover we rewrite any headers that refer to the proxy server on the request with the configured host and vice versa on the response.

  This should ensure that CORS is not broken in browsers when a different host is being simulated based on routes in the Wrangler configuration.

Minor Changes

• #4905 148feff6 Thanks @dario-piotrowicz! - feature: add a getCf method to Miniflare instances

  add a new getCf method attached to instances of Miniflare, this getCf returns the cf object that the Miniflare instance provides to the actual workers and it depends of the core option of the same name

  Example:

  import { Miniflare } from "miniflare";
  
  const mf = new Miniflare({ ... });
  
  const cf = await mf.getCf();
  
  console.log(`country = ${cf.country} ; colo = ${cf.colo}`); // logs 'country = GB ; colo = LHR'
  

Minor Changes

• #4873 1e424ff2 Thanks @dom96! - feature: implemented basic Python support

  Here is an example showing how to construct a MiniFlare instance with a Python module:

  const mf = new Miniflare({
    modules: [
      {
        type: "PythonModule",
        path: "index",
        contents:
          "from js import Response;\ndef fetch(request):\n  return Response.new('hello')",
      },
    ],
    compatibilityFlags: ["experimental"],
  });
  

Patch Changes

• #4874 749fa3c0 Thanks @mrbbot! - chore: bump workerd to 1.20240129.0

Patch Changes

• #4812 8166eefc Thanks @petebacondarwin! - fix: ensure that Origin header is rewritten as necessary

  The wrangler dev command puts the Worker under test behind a proxy server. This proxy server should be transparent to the client and the Worker, which means that the Request arriving at the Worker with the correct url property, and Host and Origin headers. Previously we fixed the Host header but missed the Origin header which is only added to a request under certain circumstances, such as cross-origin requests.

  This change fixes the Origin header as well, so that it is rewritten, when it exists, to use the origin of the url property.

  Fixes #4761

Patch Changes

• #4768 c3e410c2 Thanks @petebacondarwin! - ci: bump undici versions to 5.28.2

Minor Changes

• #4686 4f6999ea Thanks @mrbbot! - feat: expose rows_read and rows_written in D1 result meta

  rows_read/rows_written contain the number of rows read from/written to the database engine when executing a query respectively. These numbers may be greater than the number of rows returned from/inserted by a query. These numbers form billing metrics when your Worker is deployed. See https://developers.cloudflare.com/d1/platform/pricing/#billing-metrics for more details.

Patch Changes

• #4719 c37d94b5 Thanks @mrbbot! - fix: ensure miniflare and wrangler can source map in the same process

  Previously, if in a wrangler dev session you called console.log() and threw an unhandled error you'd see an error like [ERR_ASSERTION]: The expression evaluated to a falsy value. This change ensures you can do both of these things in the same session.

Patch Changes

• #4630 037de5ec Thanks @petebacondarwin! - fix: ensure User Worker gets the correct Host header in wrangler dev local mode

  Some full-stack frameworks, such as Next.js, check that the Host header for a server side action request matches the host where the application is expected to run.

  In wrangler dev we have a Proxy Worker in between the browser and the actual User Worker. This Proxy Worker is forwarding on the request from the browser, but then the actual User Worker is running on a different host:port combination than that which the browser thinks it should be on. This was causing the framework to think the request is malicious and blocking it.

  Now we update the request's Host header to that passed from the Proxy Worker in a custom MF-Original-Url header, but only do this if the request also contains a shared secret between the Proxy Worker and User Worker, which is passed via the MF-Proxy-Shared-Secret header. This last feature is to prevent a malicious website from faking the Host header in a request directly to the User Worker.

  Fixes https://github.com/cloudflare/next-on-pages/issues/588

Minor Changes

• #4684 c410ea14 Thanks @mrbbot! - chore: bump workerd to 1.20231218.0

Patch Changes

• #4448 eb08e2dc Thanks @mrbbot! - fix: include request url and headers in pretty error page

  This change ensures Miniflare's pretty error page includes the URL and headers of the incoming request, rather than Miniflare's internal request for the page.

Patch Changes

• #4466 71fb0b86 Thanks @mrbbot! - fix: ensure unused KV and Cache blobs cleaned up

  When storing data in KV, Cache and R2, Miniflare uses both an SQL database and separate blob store. When writing a key/value pair, a blob is created for the new value and the old blob for the previous value (if any) is deleted. A few months ago, we introduced a change that prevented old blobs being deleted for KV and Cache. R2 was unaffected. This shouldn't have caused any problems, but could lead to persistence directories growing unnecessarily as they filled up with garbage blobs. This change ensures garbage blobs are deleted.

  Note existing garbage will not be cleaned up. If you'd like to do this, download this Node script (https://gist.github.com/mrbbot/68787e19dcde511bd99aa94997b39076). If you're using the default Wrangler persistence directory, run node gc.mjs kv .wrangler/state/v3/kv <namespace_id_1> <namespace_id_2> ... and node gc.mjs cache .wrangler/state/v3/cache default named:<cache_name_1> named:<cache_name_2> ... with each of your KV namespace IDs (not binding names) and named caches.

• #4550 63708a94 Thanks @mrbbot! - fix: validate Host and Orgin headers where appropriate

  Host and Origin headers are now checked when connecting to the inspector and Miniflare's magic proxy. If these don't match what's expected, the request will fail.

Patch Changes

• #4505 1b348782 Thanks @mrbbot! - fix: remove __STATIC_CONTENT_MANIFEST from module worker env

  When using Workers Sites with a module worker, the asset manifest must be imported from the __STATIC_CONTENT_MANIFEST virtual module. Miniflare provided this module, but also erroneously added __STATIC_CONTENT_MANIFEST to the env object too. Whilst this didn't break anything locally, it could cause users to develop Workers that ran locally, but not when deployed. This change ensures env doesn't contain __STATIC_CONTENT_MANIFEST.

Minor Changes

• #4348 be2b9cf5 Thanks @mrbbot! - feat: add support for wrapped bindings

  This change adds a new wrappedBindings worker option for configuring workerd's wrapped bindings. These allow custom bindings to be written as JavaScript functions accepting an env parameter of "inner bindings" and returning the value to bind. For more details, refer to the API docs.

• #4341 d9908743 Thanks @RamIdeas! - Added a handleRuntimeStdio which enables wrangler (or any other direct use of Miniflare) to handle the stdout and stderr streams from the workerd child process. By default, if this option is not provided, the previous behaviour is retained which splits the streams into lines and calls console.log/console.error.

Minor Changes

• #4324 16cc2e92 Thanks @penalosa! - Update to latest workerd@1.20231030.0

• #4322 8a25b7fb Thanks @dario-piotrowicz! - add unsafeEvalBinding option

  Add option to leverage the newly introduced UnsafeEval workerd binding API, such API is used to evaluate javascript code at runtime via the provided eval and newFunction methods.

  The API, for security reasons (as per the workers docs), is not to be use in production but it is intended for local purposes only such as local testing.

  To use the binding you need to specify a string value for the unsafeEvalBinding, such will be the name of the UnsafeEval bindings that will be made available in the workerd runtime.

  For example the following code shows how to set the binding with the UNSAFE_EVAL name and evaluate the 1+1 string:

  const mf = new Miniflare({
    log,
    modules: true,
    script: `
        export default {
            fetch(req, env, ctx) {
                const two = env.UNSAFE_EVAL.eval('1+1');
                return new Response('two = ' + two); // returns 'two = 2'
            }
        }
    `,
    unsafeEvalBinding: "UNSAFE_EVAL",
  });
  

Patch Changes

• #4397 4f8b3420 Thanks @mrbbot! - fix: reject Miniflare#ready promise if Miniflare#dispose() called while waiting

• #4428 3637d97a Thanks @mrbbot! - fix: add miniflare bin entry

  Miniflare 3 doesn't include a CLI anymore, but should log a useful error stating this when running npx miniflare. We had a script for this, but it wasn't correctly hooked up. :facepalm: This change makes sure the required bin entry exists.

• #4321 29a59d4e Thanks @mrbbot! - fix: ensure Mutex doesn't report itself as drained if locked

  Previously, Miniflare's Mutex implementation would report itself as drained if there were no waiters, regardless of the locked state. This bug meant that if you called but didn't await Miniflare#setOptions(), future calls to Miniflare#dispatchFetch() (or any other asynchronous Miniflare method) wouldn't wait for the options update to apply and the runtime to restart before sending requests. This change ensures we wait until the mutex is unlocked before reporting it as drained.

• #4307 7fbe1937 Thanks @jspspike! - Only output ipv4 addresses when starting

• #4400 76787861 Thanks @mrbbot! - fix: cleanup temporary directory after shutting down workerd

  Previously on exit, Miniflare would attempt to remove its temporary directory before shutting down workerd. This could lead to EBUSY errors on Windows. This change ensures we shutdown workerd before removing the directory. Since we can only clean up on a best effort basis when exiting, it also catches any errors thrown when removing the directory, in case the runtime doesn't shutdown fast enough.