Merge pull request #16 from mrbbot/docs/1.3.0

Version 1.3.0 Docs

Author: mrbbot

CHANGELOG.md

@@ -1,5 +1,35 @@
 # 🚧 Changelog
 
+## 1.3.0
+
+### Features
+
+- Switched to a [`lol-html`](https://github.com/cloudflare/lol-html)-based
+  WebAssembly implementation of `HTMLRewriter` for a more accurate simulation of
+  the real Workers environment. See
+  [📄 HTMLRewriter](https://miniflare.dev/html-rewriter.html) for more details.
+- Added HTTPS support for local development, thanks
+  [@RichiCoder1](https://github.com/RichiCoder1) for the
+  [suggestion (#12)](https://github.com/mrbbot/miniflare/issues/12). See
+  [💻 Using the CLI](https://miniflare.dev/cli.html#https-server) and
+  [🧰 Using the API](https://miniflare.dev/api.html#https-server) for more
+  details.
+- When using the CLI, the `--watch` flag is now assumed if `--build-watch-path`
+  is set, thanks [@evanderkoogh](https://github.com/evanderkoogh) for the
+  [PR (#8)](https://github.com/mrbbot/miniflare/pull/8)
+- Added source maps to `CommonJS` module transformation
+
+### Fixes
+
+- Switched to real values for the `cf` property, thanks
+  [@chase](https://github.com/chase) for the
+  [PR (#11)](https://github.com/mrbbot/miniflare/pull/11)
+- Upgraded the TOML parser to support dotted keys, thanks
+  [@leader22](https://github.com/leader22) for the
+  [PR (#13)](https://github.com/mrbbot/miniflare/pull/13)
+- Added `CryptoKey` to the sandbox, thanks [@mosch](https://github.com/mosch)
+  for the [PR (#14)](https://github.com/mrbbot/miniflare/pull/14)
+
 ## 1.2.0
 
 ### Features

README.md

@@ -13,12 +13,14 @@
 It's an alternative to `wrangler dev`, written in TypeScript, that runs your
 workers in a sandbox implementing Workers' runtime APIs.
 
+Note that Miniflare is not an official Cloudflare product.
+
 **See <https://miniflare.dev> for more detailed documentation.**
 
 ## Features
 
-- 📨 Fetch Events (with HTTP server and manual triggering)
-- ⏰ Scheduled Events (with manual and cron triggering)
+- 📨 Fetch Events (with HTTP(S) server and manual dispatch)
+- ⏰ Scheduled Events (with cron triggering and manual dispatch)
 - 🔑 Variables and Secrets with `.env` Files
 - 📚 Modules Support
 - 📦 KV (with optional persistence)
@@ -106,6 +108,12 @@ Options:
   -e, --env               Path to .env file                             [string]
   -b, --binding           Bind variable/secret (KEY=VALUE)               [array]
       --wasm              WASM module to bind (NAME=PATH)                [array]
+      --https             Enable self-signed HTTPS
+      --https-key         Path to PEM SSL key                           [string]
+      --https-cert        Path to PEM SSL cert chain                    [string]
+      --https-ca          Path to SSL trusted CA certs                  [string]
+      --https-pfx         Path to PFX/PKCS12 SSL key/cert chain         [string]
+      --https-passphrase  Passphrase to decrypt SSL files               [string]
       --disable-updater   Disable update checker                       [boolean]
 ```
 

docs/api.md

@@ -44,7 +44,7 @@ The [Guide](/fetch.html) goes into more detail on configuring specific features.
 <!--prettier-ignore-start-->
 ::: warning
 Like the CLI, the API will automatically load `.env`, `package.json` and `wrangler.toml` files
-in the current working directory. This may lead to unexpected results. You can
+in the current working directory. This may lead to unexpected behaviour. You can
 disable this by setting `envPath`, `packagePath` and `wranglerConfigPath` options to paths of
 empty files:
 
@@ -75,9 +75,9 @@ const mf = new Miniflare({
 
 ### Watching, Reloading and Disposing
 
-You can watch scripts, `.env` files and `wrangler.toml` files with the `watch`
-option. When this is enabled, you must `dispose` of the watcher when you're done
-with the `Miniflare` instance:
+You can watch scripts, `.env`, `package.json` and `wrangler.toml` files with the
+`watch` option. When this is enabled, you must `dispose` of the watcher when
+you're done with the `Miniflare` instance:
 
 ```js
 const mf = new Miniflare({
@@ -90,8 +90,8 @@ await mf.dispose();
 You must also `dispose` if you're persisting KV, cache, or Durable Object data
 in Redis to close opened connections.
 
-You can also manually reload scripts (main and Durable Object's) and options
-(`.env` and `wrangler.toml`) too with `reloadOptions`:
+You can also manually reload scripts (main and Durable Objects') and options
+(`.env`, `package.json` and `wrangler.toml`) too with `reloadOptions`:
 
 ```js
 const mf = new Miniflare({ ... });
@@ -101,8 +101,8 @@ await mf.reloadOptions();
 ### Getting Processed Options
 
 You can get an object containing processed options with `getOptions`. These
-contain options resolved from the constructor, `.env` files and `wrangler.toml`
-files.
+contain options resolved from the constructor, `.env`, `package.json` and
+`wrangler.toml` files:
 
 ```js
 const mf = new Miniflare({ ... });
@@ -173,6 +173,69 @@ const port = options.port ?? 5000; // Use port 5000 by default
 mf.createServer().listen(port, () => { ... });
 ```
 
+### HTTPS Server
+
+To start an HTTPS server instead, set the `https` option as described below and
+pass `true` as the secure argument of `createServer`. Note that you must now
+`await` the call to `createServer`:
+
+```js
+import { Miniflare } from "miniflare";
+
+const mf = new Miniflare({
+  ...,
+  https: ...
+});
+(await mf.createServer(true)).listen(5000, () => {
+  console.log("Listening on :5000");
+});
+```
+
+To use an automatically generated self-signed certificate, set `https` to
+`true`. This certificate will be valid for 30 days and be cached in `./.mf/cert`
+by default. You can customise this directory by setting `https` to a string path
+instead. The certificate will be renewed if it expires in less than 2 days:
+
+```js
+const mf = new Miniflare({
+  https: true, // Cache certificate in ./.mf/cert
+  https: "./cert_cache", // Cache in ./cert_cache instead
+});
+```
+
+To load an existing certificate from the file system:
+
+```js
+const mf = new Miniflare({
+  https: {
+    // These are all optional, you don't need to include them all
+    keyPath: "./key.pem",
+    certPath: "./cert.pem",
+    caPath: "./ca.pem",
+    pfxPath: "./pfx.pfx",
+    passphrase: "pfx passphrase",
+  },
+});
+```
+
+To load an existing certificate from strings instead:
+
+```js
+const mf = new Miniflare({
+  https: {
+    // These are all optional, you don't need to include them all
+    key: "-----BEGIN RSA PRIVATE KEY-----...",
+    cert: "-----BEGIN CERTIFICATE-----...",
+    ca: "...",
+    pfx: "...",
+    passphrase: "pfx passphrase",
+  },
+});
+```
+
+If both a string and path are specified for an option (e.g. `key` and
+`keyPath`), the string will be preferred.
+
 ### Logging
 
 By default, `[mf:*]` logs as seen in the CLI are disabled when using the API. To

docs/builds.md

@@ -42,6 +42,13 @@ dir = "" # Defaults to "dist"
 main = "./output.js"
 ```
 
+<!--prettier-ignore-start-->
+::: tip
+When using the CLI, if `--build-watch-path` is set, `--watch` is automatically
+assumed.
+:::
+<!--prettier-ignore-end-->
+
 ## Wrangler Builds
 
 Miniflare supports building `webpack` and `rust` type Wrangler projects too.

docs/cache.md

@@ -30,22 +30,22 @@ but not CLI invocations or different `Miniflare` instances. To enable
 persistence to the file system or Redis, specify the cache persistence option:
 
 ```shell
-$ miniflare --cache-persist # Defaults to ./mf/cache
+$ miniflare --cache-persist # Defaults to ./.mf/cache
 $ miniflare --cache-persist ./data/  # Custom path
 $ miniflare --cache-persist redis://localhost:6379  # Redis server
 ```
 
 ```toml
 # wrangler.toml
 [miniflare]
-cache_persist = true # Defaults to ./mf/cache
+cache_persist = true # Defaults to ./.mf/cache
 cache_persist = "./data/" # Custom path
 cache_persist = "redis://localhost:6379" # Redis server
 ```
 
 ```js
 const mf = new Miniflare({
-  cachePersist: true, // Defaults to ./mf/cache
+  cachePersist: true, // Defaults to ./.mf/cache
   cachePersist: "./data", // Custom path
   cachePersist: "redis://localhost:6379", // Redis server
 });

docs/cli.md

@@ -40,8 +40,13 @@ $ miniflare worker.js
 
 <!--prettier-ignore-start-->
 ::: tip
-If you're building your worker beforehand, make sure you pass the path of your built output to Miniflare, not your input source code.
-See [🛠 Builds](/builds.html) for more details.
+If you're building your worker beforehand (with esbuild, Webpack, etc), make
+sure you pass the path of your built output to Miniflare, not your input source
+code. See [🛠 Builds](/builds.html) for more details.
+
+If your script is defined in a `wrangler.toml` or `package.json` file, or you're
+using Wrangler's `"webpack"` or `"rust"` worker `type`s, you don't need to pass
+a script as a command line argument: Miniflare will infer it automatically.
 :::
 <!--prettier-ignore-end-->
 
@@ -113,6 +118,27 @@ main = "./worker.js"
 }
 ```
 
+### HTTPS Server
+
+By default, Miniflare starts an HTTP server. To start an HTTPS server instead,
+set the `https` option. To use an automatically generated self-signed
+certificate, use the `--https` flag. This certificate is cached and will be
+valid for 30 days. The certificate will be renewed if it expires in less than 2
+days:
+
+```shell
+$ miniflare worker.js --https # Cache certificate in ./.mf/cert
+$ miniflare worker.js --https ./cert_cache # Cache in ./cert_cache instead
+```
+
+To use an existing certificate instead, use the `--https-key`, `--https-cert`,
+`--https-ca` and `--https-pfx` to set the paths to it. If these are encrypted,
+use the `--https-passphrase` flag to set the passphrase:
+
+```shell
+$ miniflare worker.js --https-key ./key.pem --https-cert ./cert.pem
+```
+
 ### Update Checker
 
 The CLI includes an automatic update checker that looks for new versions of
@@ -157,6 +183,12 @@ Options:
   -e, --env               Path to .env file                             [string]
   -b, --binding           Bind variable/secret (KEY=VALUE)               [array]
       --wasm              WASM module to bind (NAME=PATH)                [array]
+      --https             Enable self-signed HTTPS
+      --https-key         Path to PEM SSL key                           [string]
+      --https-cert        Path to PEM SSL cert chain                    [string]
+      --https-ca          Path to SSL trusted CA certs                  [string]
+      --https-pfx         Path to PFX/PKCS12 SSL key/cert chain         [string]
+      --https-passphrase  Passphrase to decrypt SSL files               [string]
       --disable-updater   Disable update checker                       [boolean]
 ```
 
@@ -210,4 +242,12 @@ port = 1337                        ## --port
 wasm_bindings = [                  ## --wasm
   { name = "MODULE", path="module.wasm" }
 ]
+https = true                       ## --https
+https = "./cert_cache"             ## --https ./cert_cache
+[miniflare.https]
+key = "./key.pem"                  ## --https-key
+cert = "./cert.pem"                ## --https-cert
+ca = "./ca.pem"                    ## --https-ca
+pfx = "./pfx.pfx"                  ## --https-pfx
+passphrase = "pfx passphrase"      ## --https-passphrase
 ```

docs/durable-objects.md

@@ -62,22 +62,22 @@ persistence to the file system or Redis, specify the Durable Object persistence
 option:
 
 ```shell
-$ miniflare --do-persist # Defaults to ./mf/do
+$ miniflare --do-persist # Defaults to ./.mf/do
 $ miniflare --do-persist ./data/  # Custom path
 $ miniflare --do-persist redis://localhost:6379  # Redis server
 ```
 
 ```toml
 # wrangler.toml
 [miniflare]
-durable_objects_persist = true # Defaults to ./mf/do
+durable_objects_persist = true # Defaults to ./.mf/do
 durable_objects_persist = "./data/" # Custom path
 durable_objects_persist = "redis://localhost:6379" # Redis server
 ```
 
 ```js
 const mf = new Miniflare({
-  durableObjectsPersist: true, // Defaults to ./mf/do
+  durableObjectsPersist: true, // Defaults to ./.mf/do
   durableObjectsPersist: "./data", // Custom path
   durableObjectsPersist: "redis://localhost:6379", // Redis server
 });

docs/html-rewriter.md

@@ -2,14 +2,7 @@
 
 - [`HTMLRewriter` Reference](https://developers.cloudflare.com/workers/runtime-apis/html-rewriter)
 
-Miniflare includes `HTMLRewriter` in its sandbox. It is powered by
-[@worker-tools/parsed-html-rewriter](https://github.com/worker-tools/parsed-html-rewriter).
-Note this isn't a streaming parser: the entire document is parsed, then
-rewritten. This makes it slower and more memory inefficient than the actual
-implementation. This also means the order handlers are called may be different
-to real workers.
-
-Ideally, we would use a WebAssembly version of
-[lol-html](https://github.com/cloudflare/lol-html), the actual streaming parser
-Cloudflare Workers use, but this
-[isn't available yet](https://github.com/cloudflare/lol-html/issues/38).
+Miniflare includes `HTMLRewriter` in its sandbox. It's powered by
+[`html-rewriter-wasm`](https://github.com/mrbbot/html-rewriter-wasm), which uses
+a WebAssembly version of [`lol-html`](https://github.com/cloudflare/lol-html),
+the same library Cloudflare Workers use for their `HTMLRewriter`.

docs/kv.md

@@ -53,22 +53,22 @@ not CLI invocations or different `Miniflare` instances. To enable persistence to
 the file system or Redis, specify the KV persistence option:
 
 ```shell
-$ miniflare --kv-persist # Defaults to ./mf/kv
+$ miniflare --kv-persist # Defaults to ./.mf/kv
 $ miniflare --kv-persist ./data/  # Custom path
 $ miniflare --kv-persist redis://localhost:6379  # Redis server
 ```
 
 ```toml
 # wrangler.toml
 [miniflare]
-kv_persist = true # Defaults to ./mf/kv
+kv_persist = true # Defaults to ./.mf/kv
 kv_persist = "./data/" # Custom path
 kv_persist = "redis://localhost:6379" # Redis server
 ```
 
 ```js
 const mf = new Miniflare({
-  kvPersist: true, // Defaults to ./mf/kv
+  kvPersist: true, // Defaults to ./.mf/kv
   kvPersist: "./data", // Custom path
   kvPersist: "redis://localhost:6379", // Redis server
 });

package.json

@@ -1,6 +1,6 @@
 {
   "name": "miniflare",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Fun, full-featured, fully-local simulator for Cloudflare Workers",
   "keywords": [
     "cloudflare",