From 109ebc14fda92bc2c84459b9911bef03b08f1b0a Mon Sep 17 00:00:00 2001 From: Colin McDonnell Date: Thu, 6 Jul 2023 13:02:29 -0700 Subject: Various docs updates (#3437) * Various docs updates * Add mocks page * Fix make * WebKit instructions * Update instructions * Updates * Update nodejs compat table * Document trusted deps * Tweak trustedDependencies docs * Document --exact * Update test docs * Tweaks * Boring * Remove redundant j * Undo makefile changes * Undo makefile changes * Update page title * Regen * Undo changes --- docs/api/http.md | 107 +++++++++++++++++++++++++++++++++------------------- docs/api/streams.md | 6 +-- 2 files changed, 72 insertions(+), 41 deletions(-) (limited to 'docs/api') diff --git a/docs/api/http.md b/docs/api/http.md index aed9da27c..8520604e8 100644 --- a/docs/api/http.md +++ b/docs/api/http.md @@ -67,7 +67,7 @@ Bun.serve({ fetch(req) { throw new Error("woops!"); }, - error(error: Error) { + error(error) { return new Response(`
${error}\n${error.stack}
`, { headers: { "Content-Type": "text/html", @@ -95,37 +95,37 @@ server.stop(); ## TLS -Bun supports TLS out of the box, powered by [OpenSSL](https://www.openssl.org/). Enable TLS by passing in a value for `key` and `cert`; both are required to enable TLS. If needed, supply a `passphrase` to decrypt the `keyFile`. +Bun supports TLS out of the box, powered by [BoringSSL](https://boringssl.googlesource.com/boringssl). Enable TLS by passing in a value for `key` and `cert`; both are required to enable TLS. -```ts -Bun.serve({ - fetch(req) { - return new Response("Hello!!!"); - }, - - // can be string, BunFile, TypedArray, Buffer, or array thereof - key: Bun.file("./key.pem"), - cert: Bun.file("./cert.pem"), +```ts-diff + Bun.serve({ + fetch(req) { + return new Response("Hello!!!"); + }, - // passphrase, only required if key is encrypted - passphrase: "super-secret", -}); ++ tls: { ++ key: Bun.file("./key.pem"), ++ cert: Bun.file("./cert.pem"), ++ } + }); ``` -The `key` and `cert` fields expect the _contents_ of your TLS key and certificate. This can be a string, `BunFile`, `TypedArray`, or `Buffer`. +The `key` and `cert` fields expect the _contents_ of your TLS key and certificate, _not a path to it_. This can be a string, `BunFile`, `TypedArray`, or `Buffer`. ```ts Bun.serve({ fetch() {}, - // BunFile - key: Bun.file("./key.pem"), - // Buffer - key: fs.readFileSync("./key.pem"), - // string - key: fs.readFileSync("./key.pem", "utf8"), - // array of above - key: [Bun.file('./key1.pem'), Bun.file('./key2.pem')], + tls: { + // BunFile + key: Bun.file("./key.pem"), + // Buffer + key: fs.readFileSync("./key.pem"), + // string + key: fs.readFileSync("./key.pem", "utf8"), + // array of above + key: [Bun.file("./key1.pem"), Bun.file("./key2.pem")], + }, }); ``` @@ -135,17 +135,35 @@ Bun.serve({ {% /callout %} +If your private key is encrypted with a passphrase, provide a value for `passphrase` to decrypt it. + +```ts-diff + Bun.serve({ + fetch(req) { + return new Response("Hello!!!"); + }, + + tls: { + key: Bun.file("./key.pem"), + cert: Bun.file("./cert.pem"), ++ passphrase: "my-secret-passphrase", + } + }); +``` + Optionally, you can override the trusted CA certificates by passing a value for `ca`. By default, the server will trust the list of well-known CAs curated by Mozilla. When `ca` is specified, the Mozilla list is overwritten. -```ts -Bun.serve({ - fetch(req) { - return new Response("Hello!!!"); - }, - key: Bun.file("./key.pem"), // path to TLS key - cert: Bun.file("./cert.pem"), // path to TLS cert - ca: Bun.file("./ca.pem"), // path to root CA certificate -}); +```ts-diff + Bun.serve({ + fetch(req) { + return new Response("Hello!!!"); + }, + tls: { + key: Bun.file("./key.pem"), // path to TLS key + cert: Bun.file("./cert.pem"), // path to TLS cert ++ ca: Bun.file("./ca.pem"), // path to root CA certificate + } + }); ``` To override Diffie-Helman parameters: @@ -153,7 +171,10 @@ To override Diffie-Helman parameters: ```ts Bun.serve({ // ... - dhParamsFile: "./dhparams.pem", // path to Diffie Helman parameters + tls: { + // other config + dhParamsFile: "/path/to/dhparams.pem", // path to Diffie Helman parameters + }, }); ``` @@ -274,11 +295,21 @@ interface Bun { port?: number; development?: boolean; error?: (error: Error) => Response | Promise; - keyFile?: string; - certFile?: string; - caFile?: string; - dhParamsFile?: string; - passphrase?: string; + tls?: { + key?: + | string + | TypedArray + | BunFile + | Array; + cert?: + | string + | TypedArray + | BunFile + | Array; + ca?: string | TypedArray | BunFile | Array; + passphrase?: string; + dhParamsFile?: string; + }; maxRequestBodySize?: number; lowMemoryMode?: boolean; }): Server; diff --git a/docs/api/streams.md b/docs/api/streams.md index 7f3e3bcb4..210090927 100644 --- a/docs/api/streams.md +++ b/docs/api/streams.md @@ -28,8 +28,6 @@ for await (const chunk of stream) { } ``` -For a more complete discusson of streams in Bun, see [API > Streams](/docs/api/streams). - ## Direct `ReadableStream` Bun implements an optimized version of `ReadableStream` that avoid unnecessary data copying & queue management logic. With a traditional `ReadableStream`, chunks of data are _enqueued_. Each chunk is copied into a queue, where it sits until the stream is ready to send more data. @@ -154,7 +152,9 @@ export class ArrayBufferSink { stream?: boolean; }): void; - write(chunk: string | ArrayBufferView | ArrayBuffer | SharedArrayBuffer): number; + write( + chunk: string | ArrayBufferView | ArrayBuffer | SharedArrayBuffer, + ): number; /** * Flush the internal buffer * -- cgit v1.2.3 From 609f81a74614b20a1d49ce1197e1ddfe5aa2736f Mon Sep 17 00:00:00 2001 From: Colin McDonnell Date: Tue, 11 Jul 2023 15:32:41 -0700 Subject: Add npmrc note --- docs/api/file-io.md | 12 ++++++++++-- docs/install/registries.md | 4 ++++ 2 files changed, 14 insertions(+), 2 deletions(-) (limited to 'docs/api') diff --git a/docs/api/file-io.md b/docs/api/file-io.md index effc57580..be9cf0991 100644 --- a/docs/api/file-io.md +++ b/docs/api/file-io.md @@ -285,7 +285,13 @@ interface Bun { write( destination: string | number | BunFile | URL, - input: string | Blob | ArrayBuffer | SharedArrayBuffer | TypedArray | Response, + input: + | string + | Blob + | ArrayBuffer + | SharedArrayBuffer + | TypedArray + | Response, ): Promise; } @@ -301,7 +307,9 @@ interface BunFile { } export interface FileSink { - write(chunk: string | ArrayBufferView | ArrayBuffer | SharedArrayBuffer): number; + write( + chunk: string | ArrayBufferView | ArrayBuffer | SharedArrayBuffer, + ): number; flush(): number | Promise; end(error?: Error): number | Promise; start(options?: { highWaterMark?: number }): void; diff --git a/docs/install/registries.md b/docs/install/registries.md index e4090e3c9..86657ca26 100644 --- a/docs/install/registries.md +++ b/docs/install/registries.md @@ -24,3 +24,7 @@ To configure a private registry scoped to a particular organization: # registry with token "@myorg3" = { token = "$npm_token", url = "https://registry.myorg.com/" } ``` + +### `.npmrc` + +Bun does not currently read `.npmrc` files. For private registries, migrate your registry configuration to `bunfig.toml` as documented above. -- cgit v1.2.3