Fastify plugin to forward the current HTTP request to another server. HTTP2 to HTTP is supported too.
npm i @fastify/reply-from
@fastify/reply-from and @fastify/multipart should not be registered as sibling plugins nor should they be registered in plugins that have a parent-child relationship.<br> The two plugins are incompatible, in the sense that the behavior of @fastify/reply-from might not be the expected one when the above-mentioned conditions are not respected.<br> This is due to the fact that @fastify/multipart consumes the multipart content by parsing it, hence this content is not forwarded to the target service by @fastify/reply-from.<br> However, the two plugins may be used within the same fastify instance, at the condition that they belong to disjoint branches of the fastify plugins hierarchy tree.
The following example set up two Fastify servers and forward the request from one to the other:
'use strict'
const Fastify = require('fastify')
const target = Fastify({
logger: true
})
target.get('/', (request, reply) => {
reply.send('hello world')
})
const proxy = Fastify({
logger: true
})
proxy.register(require('@fastify/reply-from'), {
base: 'http://localhost:3001/'
})
proxy.get('/', (request, reply) => {
reply.from('/')
})
target.listen({ port: 3001 }, (err) => {
if (err) {
throw err
}
proxy.listen({ port: 3000 }, (err) => {
if (err) {
throw err
}
})
})
Set the base URL for all the forwarded requests. Will be required if http2 is set to true Note that every path will be discarded.
Set the base URL for all the forwarded requests.
String or String[]:
undici.Pool / http.request client is used.undici.BalancedPool is automatically selected and requests are load-balanced round-robin across the given origins.When you provide an array, only the origin (protocol://host:port) part of each URL is considered; any path component is ignored.
Custom URL protocols unix+http: and unix+https: can be used to forward requests to a unix socket server by using querystring.escape(socketPath) as the hostname. This is not supported for http2 nor undici. To illustrate:
const socketPath = require('node:querystring').escape('/run/http-daemon.socket')
proxy.register(require('@fastify/reply-from'), {
base: 'unix+http://${socketPath}/'
});
By default, undici will be used to perform the HTTP/1.1 requests. Enabling this option should guarantee 20-50% more throughput.
This option controls the settings of the undici client, like so:
proxy.register(require('@fastify/reply-from'), {
base: 'http://localhost:3001/',
// default settings
undici: {
connections: 128,
pipelining: 1,
keepAliveTimeout: 60 * 1000,
tls: {
rejectUnauthorized: false
}
}
})
You can also include a proxy for the undici client:
proxy.register(require('@fastify/reply-from'), {
base: 'http://localhost:3001/',
undici: {
proxy: 'http://my.proxy.server:8080',
}
})
See undici own options for more configurations.
You can also pass the plugin a custom instance:
proxy.register(require('@fastify/reply-from'), {
base: 'http://localhost:3001/',
undici: new undici.Pool('http://localhost:3001')
})
You can also use with BalancedPool:
proxy.register(require('@fastify/reply-from'), {
base: [
'http://api-1.internal:8080',
'http://api-2.internal:8080',
'http://api-3.internal:8080'
]
})
Set the http option to an Object to use Node's http.request will be used if you do not enable http2. To customize the request, you can pass in agentOptions and requestOptions. To illustrate:
proxy.register(require('@fastify/reply-from'), {
base: 'http://localhost:3001/',
http: {
agentOptions: { // pass in any options from https://nodejs.org/api/http.html#http_new_agent_options
keepAliveMsecs: 10 * 60 * 1000
},
requestOptions: { // pass in any options from https://nodejs.org/api/http.html#http_http_request_options_callback
timeout: 5000 // timeout in msecs, defaults to 10000 (10 seconds)
}
}
})
You can also pass custom HTTP agents. If you pass the agents, then the http.agentOptions will be ignored. To illustrate:
proxy.register(require('@fastify/reply-from'), {
base: 'http://localhost:3001/',
http: {
agents: {
'http:': new http.Agent({ keepAliveMsecs: 10 * 60 * 1000 }), // pass in any options from https://nodejs.org/api/http.html#http_new_agent_options
'https:': new https.Agent({ keepAliveMsecs: 10 * 60 * 1000 })
},
requestOptions: { // pass in any options from https://nodejs.org/api/http.html#http_http_request_options_callback
timeout: 5000 // timeout in msecs, defaults to 10000 (10 seconds)
}
}
})
You can either set http2 to true or set the settings object to connect to an HTTP/2 server. The http2 settings object has the shape of:
proxy.register(require('@fastify/reply-from'), {
base: 'http://localhost:3001/',
http2: {
sessionTimeout: 10000, // HTTP/2 session timeout in msecs, defaults to 60000 (1 minute)
requestTimeout: 5000, // HTTP/2 request timeout in msecs, defaults to 10000 (10 seconds)
sessionOptions: { // HTTP/2 session connect options, pass in any options from https://nodejs.org/api/http2.html#http2_http2_connect_authority_options_listener
rejectUnauthorized: true
},
requestOptions: { // HTTP/2 request options, pass in any options from https://nodejs.org/api/http2.html#clienthttp2sessionrequestheaders-options
endStream: true
}
}
})
By default, the package will issue log messages when a request is received. By setting this option to true, these log messages will be disabled.
Default for disableRequestLogging will be false. To disable the log messages set disableRequestLogging to true.
proxy.register(require('@fastify/reply-from'), {
base: 'http://localhost:3001/',
disableRequestLogging: true // request log messages will be disabled
})
The number of parsed URLs that will be cached. Default: 100.
This option will disable the URL caching. This cache is dedicated to reducing the amount of URL object generation. Generating URLs is a main bottleneck of this module, please disable this cache with caution.
An array of content types whose response body will be passed through JSON.stringify(). This only applies when a custom body is not passed in. Defaults to:
On which methods should the connection be retried in case of socket hang up. Be aware that setting here not idempotent method may lead to unexpected results on target.
By default: ['GET', 'HEAD', 'OPTIONS', 'TRACE']
This plugin will always retry on 503 errors, unless retryMethods does not contain GET.
Enables the possibility to explicitly opt-in for global agents.
Usage for undici global agent:
import { setGlobalDispatcher, ProxyAgent } from 'undici'
const proxyAgent = new ProxyAgent('my.proxy.server')
setGlobalDispatcher(proxyAgent)
fastify.register(FastifyReplyFrom, {
base: 'http://localhost:3001/',
globalAgent: true
})
Usage for http/https global agent:
fastify.register(FastifyReplyFrom, {
base: 'http://localhost:3001/',
// http and https is allowed to use http.globalAgent or https.globalAgent
globalAgent: true,
http: {
}
})
If set to true, it will destroy all agents when the Fastify is closed. If set to false, it will not destroy the agents.
By Default: false
This plugin will always retry on GET requests that returns 503 errors, unless retryMethods does not contain GET.
This option sets the limit on how many times the plugin should retry the request, specifically for 503 errors.
By Default: 10
handler. RequiredThis plugin gives the client an option to pass their own retry callback to allow the client to define what retryDelay they would like on any retries outside the scope of what is handled by default in fastify-reply-from. To see the default please refer to index.js getDefaultDelay() If a handler is passed to the retryDelay object the onus is on the client to invoke the default retry logic in their callback otherwise default cases such as 500 will not be handled
err is the error thrown by making a request using whichever agent is configuredreq is the raw request details sent to the underlying agent. Note: this object is not a Fastify request object, but instead the low-level request for the agent.res is the raw response returned by the underlying agent (if available) Note: this object is not a Fastify response, but instead the low-level response from the agent. This property may be null if no response was obtained at all, like from a connection reset or timeout.attempt in the object callback refers to the current retriesAttempt number. You are given the freedom to use this in concert with the retryCount property set to handle retriesgetDefaultRetry refers to the default retry handler. If this callback returns not null and you wish to handle those case of errors simply invoke it as done below.retriesCount refers to the retriesCount property a client passes to reply-from. Note if the client does not explicitly set this value it will default to 0. The objective value here is to avoid hard-coding and seeing the retriesCount set. It is your prerogative to ensure that you ensure the value here is as you wish (and not 0 if not intended to be as a result of a lack of not setting it).Given example
const customRetryLogic = ({err, req, res, attempt, getDefaultRetry}) => {
//If this block is not included all non 500 errors will not be retried
const defaultDelay = getDefaultDelay(req, res, err, attempt);
if (defaultDelay) return defaultDelay();
//Custom retry logic
if (res && res.statusCode === 500 && req.method === 'GET') {
return 300
}
if (err && err.code == "UND_ERR_SOCKET"){
return 600
}
return null
}
.......
fastify.register(FastifyReplyFrom, {
base: 'http://localhost:3001/',
retryDelay: customRetryLogic
})
Note the Typescript Equivalent
const customRetryLogic = ({req, res, err, getDefaultRetry}: RetryDetails) => {
...
}
...
reply.from(source, [opts])
The plugin decorates the Reply instance with a from method, which will reply to the original request from the desired source. The options allows overrides of any part of the request or response being sent or received to/from the source.
Note: If base is specified in plugin options, the source here should not override the host/origin.
onResponse(request, reply, response)
Called when an HTTP response is received from the source. Passed the original source request, the in-progress reply to the source as reply, and the ongoing response from the upstream server.
The default behavior is reply.send(response.stream), which will be disabled if the option is specified.
When replying with a body of a different length it is necessary to remove the content-length header.
{
onResponse: (request, reply, res) => {
reply.removeHeader('content-length');
reply.send('New body of different length');
}
}
Note: onResponse is called after headers have already been sent. If you want to modify response headers, use the rewriteHeaders hook.
Called when an HTTP response is received with error from the source. The default behavior is reply.send(error), which will be disabled if the option is specified. It must reply with the error.
rewriteHeaders(headers, request)
Called to rewrite the headers of the response, before them being copied over to the outer response. Parameters are the original headers and the Fastify request. It must return the new headers object.
rewriteRequestHeaders(request, headers)
Called to rewrite the headers of the request, before them being sent to the other server. Parameters are the Fastify request and the original request headers. It must return the new headers object.
getUpstream(request, base)
Called to get upstream destination, before the request is sent. Useful when you want to decide which target server to call based on the request data. Helpful for a gradual rollout of new services. Parameters are the Fastify request and the base string from the plugin options. It must return the upstream destination.
Only http1! As http2 uses one connection for the whole session only the base upstream is used. If you want to have different upstreams based on the request you can add multiple Fastify.register's with different ContraintStrategies.
e.g.:
Route grpc-web/http1 and grpc/http2 to different routes with a ContentType-ConstraintStrategy:
const contentTypeMatchContraintStrategy = {
// strategy name for referencing in the route handler `constraints` options
name: 'contentType',
// storage factory for storing routes in the find-my-way route tree
storage: function () {
let handlers = {}
return {
get: (type: any) => { return handlers[type] || null },
set: (type: any, store: any) => { handlers[type] = store }
}
},
// function to get the value of the constraint from each incoming request
deriveConstraint: (req: any, ctx: any) => {
return req.headers['content-type']
},
// optional flag marking if handlers without constraints can match requests that have a value for this constraint
mustMatchWhenDerived: true
}
server.addConstraintStrategy(contentTypeMatchContraintStrategy);
and then 2 different upstreams with different register's:
// grpc-web / http1
server.register(fastifyHttpProxy, {
// Although most browsers send with http2, nodejs cannot handle this http2 request
// therefore we have to transport to the grpc-web-proxy via http1
http2: false,
upstream: 'http://grpc-web-proxy',
constraints: { "contentType": "application/grpc-web+proto" }
});
// grpc / http2
server.register(fastifyHttpProxy, {
http2: true,
upstream: 'http://grpc.server',
constraints: { "contentType": "application/grpc+proto" }
});
queryString or queryString(search, reqUrl, request)
Replaces the original querystring of the request with what is specified. This will be passed to querystring.stringify.
object: accepts an object that will be passed to querystring.stringifyfunction: function that will return a string with the query parameters e.g. name=test&type=userReplaces the original request body with what is specified. Unless contentType is specified, the content will be passed through JSON.stringify(). Setting this option for GET, HEAD requests will throw an error "Rewriting the body when doing a {GET|HEAD} is not allowed". Setting this option to null will strip the body (and content-type header) entirely from the proxied request.
Replaces the original request method with what is specified.
How many times it will try to pick another connection on socket hangup (ECONNRESET error). Useful when keeping the connection open (KeepAlive). This number should be a function of the number of connections and the number of instances of a target.
By default: 0 (disabled)
Override the 'Content-Type' header of the forwarded request, if we are already overriding the body.
Set a specific timeout for the request. Override options http.requestOptions.timeout, http2.requestOptions.timeout, undici.headersTimeout and undici.bodyTimeout from the plugin config.
formbody expects the body to be returned as a string and not an object. Use the contentTypesToEncode option to pass in ['application/x-www-form-urlencoded']
This library has:
timeout for http set by default. The default value is 10 seconds (10000).requestTimeout & sessionTimeout for http2 set by default.
requestTimeout is 10 seconds (10000), a value of 0 disables the timeout.sessionTimeout is 60 seconds (60000), a value of 0 disables the timeout.When a timeout happens, 504 Gateway Timeout will be returned to the client.
req.id unique (see hyperid).MIT
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4