diff options
Diffstat (limited to 'node_modules/undici/docs/best-practices')
4 files changed, 0 insertions, 347 deletions
diff --git a/node_modules/undici/docs/best-practices/client-certificate.md b/node_modules/undici/docs/best-practices/client-certificate.md deleted file mode 100644 index 4fc84ec..0000000 --- a/node_modules/undici/docs/best-practices/client-certificate.md +++ /dev/null @@ -1,64 +0,0 @@ -# Client certificate - -Client certificate authentication can be configured with the `Client`, the required options are passed along through the `connect` option. - -The client certificates must be signed by a trusted CA. The Node.js default is to trust the well-known CAs curated by Mozilla. - -Setting the server option `requestCert: true` tells the server to request the client certificate. - -The server option `rejectUnauthorized: false` allows us to handle any invalid certificate errors in client code. The `authorized` property on the socket of the incoming request will show if the client certificate was valid. The `authorizationError` property will give the reason if the certificate was not valid. - -### Client Certificate Authentication - -```js -const { readFileSync } = require('fs') -const { join } = require('path') -const { createServer } = require('https') -const { Client } = require('undici') - -const serverOptions = { - ca: [ - readFileSync(join(__dirname, 'client-ca-crt.pem'), 'utf8') - ], - key: readFileSync(join(__dirname, 'server-key.pem'), 'utf8'), - cert: readFileSync(join(__dirname, 'server-crt.pem'), 'utf8'), - requestCert: true, - rejectUnauthorized: false -} - -const server = createServer(serverOptions, (req, res) => { - // true if client cert is valid - if(req.client.authorized === true) { - console.log('valid') - } else { - console.error(req.client.authorizationError) - } - res.end() -}) - -server.listen(0, function () { - const tls = { - ca: [ - readFileSync(join(__dirname, 'server-ca-crt.pem'), 'utf8') - ], - key: readFileSync(join(__dirname, 'client-key.pem'), 'utf8'), - cert: readFileSync(join(__dirname, 'client-crt.pem'), 'utf8'), - rejectUnauthorized: false, - servername: 'agent1' - } - const client = new Client(`https://localhost:${server.address().port}`, { - connect: tls - }) - - client.request({ - path: '/', - method: 'GET' - }, (err, { body }) => { - body.on('data', (buf) => {}) - body.on('end', () => { - client.close() - server.close() - }) - }) -}) -``` diff --git a/node_modules/undici/docs/best-practices/mocking-request.md b/node_modules/undici/docs/best-practices/mocking-request.md deleted file mode 100644 index 6954392..0000000 --- a/node_modules/undici/docs/best-practices/mocking-request.md +++ /dev/null @@ -1,136 +0,0 @@ -# Mocking Request - -Undici has its own mocking [utility](../api/MockAgent.md). It allow us to intercept undici HTTP requests and return mocked values instead. It can be useful for testing purposes. - -Example: - -```js -// bank.mjs -import { request } from 'undici' - -export async function bankTransfer(recipient, amount) { - const { body } = await request('http://localhost:3000/bank-transfer', - { - method: 'POST', - headers: { - 'X-TOKEN-SECRET': 'SuperSecretToken', - }, - body: JSON.stringify({ - recipient, - amount - }) - } - ) - return await body.json() -} -``` - -And this is what the test file looks like: - -```js -// index.test.mjs -import { strict as assert } from 'assert' -import { MockAgent, setGlobalDispatcher, } from 'undici' -import { bankTransfer } from './bank.mjs' - -const mockAgent = new MockAgent(); - -setGlobalDispatcher(mockAgent); - -// Provide the base url to the request -const mockPool = mockAgent.get('http://localhost:3000'); - -// intercept the request -mockPool.intercept({ - path: '/bank-transfer', - method: 'POST', - headers: { - 'X-TOKEN-SECRET': 'SuperSecretToken', - }, - body: JSON.stringify({ - recipient: '1234567890', - amount: '100' - }) -}).reply(200, { - message: 'transaction processed' -}) - -const success = await bankTransfer('1234567890', '100') - -assert.deepEqual(success, { message: 'transaction processed' }) - -// if you dont want to check whether the body or the headers contain the same value -// just remove it from interceptor -mockPool.intercept({ - path: '/bank-transfer', - method: 'POST', -}).reply(400, { - message: 'bank account not found' -}) - -const badRequest = await bankTransfer('1234567890', '100') - -assert.deepEqual(badRequest, { message: 'bank account not found' }) -``` - -Explore other MockAgent functionality [here](../api/MockAgent.md) - -## Debug Mock Value - -When the interceptor and the request options are not the same, undici will automatically make a real HTTP request. To prevent real requests from being made, use `mockAgent.disableNetConnect()`: - -```js -const mockAgent = new MockAgent(); - -setGlobalDispatcher(mockAgent); -mockAgent.disableNetConnect() - -// Provide the base url to the request -const mockPool = mockAgent.get('http://localhost:3000'); - -mockPool.intercept({ - path: '/bank-transfer', - method: 'POST', -}).reply(200, { - message: 'transaction processed' -}) - -const badRequest = await bankTransfer('1234567890', '100') -// Will throw an error -// MockNotMatchedError: Mock dispatch not matched for path '/bank-transfer': -// subsequent request to origin http://localhost:3000 was not allowed (net.connect disabled) -``` - -## Reply with data based on request - -If the mocked response needs to be dynamically derived from the request parameters, you can provide a function instead of an object to `reply`: - -```js -mockPool.intercept({ - path: '/bank-transfer', - method: 'POST', - headers: { - 'X-TOKEN-SECRET': 'SuperSecretToken', - }, - body: JSON.stringify({ - recipient: '1234567890', - amount: '100' - }) -}).reply(200, (opts) => { - // do something with opts - - return { message: 'transaction processed' } -}) -``` - -in this case opts will be - -``` -{ - method: 'POST', - headers: { 'X-TOKEN-SECRET': 'SuperSecretToken' }, - body: '{"recipient":"1234567890","amount":"100"}', - origin: 'http://localhost:3000', - path: '/bank-transfer' -} -``` diff --git a/node_modules/undici/docs/best-practices/proxy.md b/node_modules/undici/docs/best-practices/proxy.md deleted file mode 100644 index bf10295..0000000 --- a/node_modules/undici/docs/best-practices/proxy.md +++ /dev/null @@ -1,127 +0,0 @@ -# Connecting through a proxy - -Connecting through a proxy is possible by: - -- Using [AgentProxy](../api/ProxyAgent.md). -- Configuring `Client` or `Pool` constructor. - -The proxy url should be passed to the `Client` or `Pool` constructor, while the upstream server url -should be added to every request call in the `path`. -For instance, if you need to send a request to the `/hello` route of your upstream server, -the `path` should be `path: 'http://upstream.server:port/hello?foo=bar'`. - -If you proxy requires basic authentication, you can send it via the `proxy-authorization` header. - -### Connect without authentication - -```js -import { Client } from 'undici' -import { createServer } from 'http' -import proxy from 'proxy' - -const server = await buildServer() -const proxyServer = await buildProxy() - -const serverUrl = `http://localhost:${server.address().port}` -const proxyUrl = `http://localhost:${proxyServer.address().port}` - -server.on('request', (req, res) => { - console.log(req.url) // '/hello?foo=bar' - res.setHeader('content-type', 'application/json') - res.end(JSON.stringify({ hello: 'world' })) -}) - -const client = new Client(proxyUrl) - -const response = await client.request({ - method: 'GET', - path: serverUrl + '/hello?foo=bar' -}) - -response.body.setEncoding('utf8') -let data = '' -for await (const chunk of response.body) { - data += chunk -} -console.log(response.statusCode) // 200 -console.log(JSON.parse(data)) // { hello: 'world' } - -server.close() -proxyServer.close() -client.close() - -function buildServer () { - return new Promise((resolve, reject) => { - const server = createServer() - server.listen(0, () => resolve(server)) - }) -} - -function buildProxy () { - return new Promise((resolve, reject) => { - const server = proxy(createServer()) - server.listen(0, () => resolve(server)) - }) -} -``` - -### Connect with authentication - -```js -import { Client } from 'undici' -import { createServer } from 'http' -import proxy from 'proxy' - -const server = await buildServer() -const proxyServer = await buildProxy() - -const serverUrl = `http://localhost:${server.address().port}` -const proxyUrl = `http://localhost:${proxyServer.address().port}` - -proxyServer.authenticate = function (req, fn) { - fn(null, req.headers['proxy-authorization'] === `Basic ${Buffer.from('user:pass').toString('base64')}`) -} - -server.on('request', (req, res) => { - console.log(req.url) // '/hello?foo=bar' - res.setHeader('content-type', 'application/json') - res.end(JSON.stringify({ hello: 'world' })) -}) - -const client = new Client(proxyUrl) - -const response = await client.request({ - method: 'GET', - path: serverUrl + '/hello?foo=bar', - headers: { - 'proxy-authorization': `Basic ${Buffer.from('user:pass').toString('base64')}` - } -}) - -response.body.setEncoding('utf8') -let data = '' -for await (const chunk of response.body) { - data += chunk -} -console.log(response.statusCode) // 200 -console.log(JSON.parse(data)) // { hello: 'world' } - -server.close() -proxyServer.close() -client.close() - -function buildServer () { - return new Promise((resolve, reject) => { - const server = createServer() - server.listen(0, () => resolve(server)) - }) -} - -function buildProxy () { - return new Promise((resolve, reject) => { - const server = proxy(createServer()) - server.listen(0, () => resolve(server)) - }) -} -``` - diff --git a/node_modules/undici/docs/best-practices/writing-tests.md b/node_modules/undici/docs/best-practices/writing-tests.md deleted file mode 100644 index 57549de..0000000 --- a/node_modules/undici/docs/best-practices/writing-tests.md +++ /dev/null @@ -1,20 +0,0 @@ -# Writing tests - -Undici is tuned for a production use case and its default will keep -a socket open for a few seconds after an HTTP request is completed to -remove the overhead of opening up a new socket. These settings that makes -Undici shine in production are not a good fit for using Undici in automated -tests, as it will result in longer execution times. - -The following are good defaults that will keep the socket open for only 10ms: - -```js -import { request, setGlobalDispatcher, Agent } from 'undici' - -const agent = new Agent({ - keepAliveTimeout: 10, // milliseconds - keepAliveMaxTimeout: 10 // milliseconds -}) - -setGlobalDispatcher(agent) -``` |