oak-http-proxy
- -Proxy middleware for Deno Oak HTTP servers.
-
- 
- 
- 
- 
-
- 
import { proxy } from "https://deno.land/x/oak_http_proxy@2.2.0/mod.ts";
+
+
+
+ oak-http-proxy
+
+
+
+
+
+
+
+
+
+
+ oak-http-proxy
+
+
+
+
+
+
+
+
+ oak-http-proxy
+
+ Proxy middleware for Deno Oak HTTP servers.
+
+
+
+
+
+
+
+
+ import { proxy } from "https://deno.land/x/oak_http_proxy@2.2.0/mod.ts";
import { Application } from "https://deno.land/x/oak@v12.6.2/mod.ts";
const app = new Application();
@@ -168,89 +83,34 @@ oak-http-proxy
await app.listen({ port: 3000 });
-
- Installation
-
-
- This is a Deno module available
- to import direct from this repo and via the
- Deno Registry.
-
-
- Before importing,
- download and install Deno.
-
-
- You can then import oak-http-proxy straight into your project:
-
- import { proxy } from "https://deno.land/x/oak_http_proxy@2.2.0/mod.ts";
+
+ Installation
+
+ This is a Deno module available to import direct from this repo and via the Deno Registry.
+ Before importing, download and install Deno.
+ You can then import oak-http-proxy straight into your project:
+ import { proxy } from "https://deno.land/x/oak_http_proxy@2.2.0/mod.ts";
-
- oak-http-proxy is also available on
- nest.land,
- a package registry for Deno on the Blockchain.
-
- import { proxy } from "https://x.nest.land/oak-http-proxy@2.2.0/mod.ts";
+ oak-http-proxy is also available on nest.land, a package registry for Deno on the Blockchain.
+ import { proxy } from "https://x.nest.land/oak-http-proxy@2.2.0/mod.ts";
-
- Docs
-
-
- -
- oak-http-proxy Type Docs
-
- -
- oak-http-proxy Deno Docs
-
- -
- License
-
- -
- Changelog
-
-
-
- Usage
-
-
- URL
-
-
- The url argument that can be a string, URL or a function that
- returns a string or URL. This is used as the url to proxy requests
- to. Query string parameters and hashes are transferred from
- incoming request urls onto the proxy url.
-
- router.get("/string", proxy("http://google.com"));
+
+ Docs
+
+
+
+ Usage
+
+
+ URL
+
+ The url argument that can be a string, URL or a function that returns a string or URL. This is used as the url to proxy requests to. Query string parameters and hashes are transferred from incoming request urls onto the proxy url.
+ router.get("/string", proxy("http://google.com"));
router.get("/url", proxy(new URL("http://google.com")));
@@ -259,40 +119,19 @@ URL
proxy((ctx) => new URL("http://google.com"))
);
-
- Note: Unmatched path segments of the incoming request url
- are not transferred to the outbound proxy URL. For
- dynamic proxy urls use the function form.
-
-
- Proxy Options
-
-
- You can also provide several options which allow you to filter,
- customize and decorate proxied requests and responses.
-
- app.use(proxy("http://google.com", proxyOptions));
+ Note: Unmatched path segments of the incoming request url are not transferred to the outbound proxy URL. For dynamic proxy urls use the function form.
+
+ Proxy Options
+
+ You can also provide several options which allow you to filter, customize and decorate proxied requests and responses.
+ app.use(proxy("http://google.com", proxyOptions));
-
- filterReq(req, res) (supports Promises)
-
-
- The filterReq option can be used to limit what
- requests are proxied.
-
-
- Return false to continue to execute the proxy; return true to skip
- the proxy for this request.
-
- app.use(
+
+ filterReq(req, res) (supports Promises)
+
+ The filterReq option can be used to limit what requests are proxied.
+ Return false to continue to execute the proxy; return true to skip the proxy for this request.
+ app.use(
"/proxy",
proxy("www.google.com", {
filterReq: (req, res) => {
@@ -301,8 +140,8 @@ filterReq(req, res) (supports Promises)
})
);
- Promise form:
- app.use(
+ Promise form:
+ app.use(
proxy("localhost:12346", {
filterReq: (req, res) => {
return new Promise((resolve) => {
@@ -312,20 +151,11 @@ filterReq(req, res) (supports Promises)
})
);
-
-
- srcResDecorator(req, res, proxyRes, proxyResData) (supports
- Promise)
-
-
-
- Decorate the inbound response object from the proxied request.
-
- router.get(
+
+ srcResDecorator(req, res, proxyRes, proxyResData) (supports Promise)
+
+ Decorate the inbound response object from the proxied request.
+ router.get(
"/proxy",
proxy("www.example.com", {
srcResDecorator: (req, res, proxyRes, proxyResData) => {
@@ -337,7 +167,7 @@
})
);
- app.use(
+ app.use(
proxy("httpbin.org", {
srcResDecorator: (req, res, proxyRes, proxyResData) => {
return new Promise((resolve) => {
@@ -351,52 +181,23 @@
})
);
-
- 304 - Not Modified
-
-
- When your proxied service returns 304 Not Modified this step will
- be skipped, since there should be no body to decorate.
-
-
- Exploiting references
-
-
- The intent is that this be used to modify the proxy response data
- only.
-
-
- Note: The other arguments are passed by reference, so you
- can currently exploit this to modify either
- response's headers, for instance, but this is not a reliable
- interface.
-
-
- memoizeUrl
-
- Defaults to true.
-
- When true, the url argument will be parsed on first
- request, and memoized for subsequent requests.
-
-
- When false, url argument will be parsed
- on each request.
-
- For example:
- function coinToss() {
+
+ 304 - Not Modified
+
+ When your proxied service returns 304 Not Modified this step will be skipped, since there should be no body to decorate.
+
+ Exploiting references
+
+ The intent is that this be used to modify the proxy response data only.
+ Note: The other arguments are passed by reference, so you can currently exploit this to modify either response's headers, for instance, but this is not a reliable interface.
+
+ memoizeUrl
+
+ Defaults to true.
+ When true, the url argument will be parsed on first request, and memoized for subsequent requests.
+ When false, url argument will be parsed on each request.
+ For example:
+ function coinToss() {
return Math.random() > 0.5;
}
@@ -410,26 +211,13 @@ memoizeUrl
})
);
-
- In this example, when memoizeUrl: false, the coinToss
- occurs on each request, and each request could get either value.
-
-
- Conversely, When memoizeUrl: true, the coinToss would
- occur on the first request, and all additional requests would
- return the value resolved on the first request.
-
-
- srcResHeaderDecorator
-
-
- Decorate the inbound response headers from the proxied request.
-
- router.get(
+ In this example, when memoizeUrl: false, the coinToss occurs on each request, and each request could get either value.
+ Conversely, When memoizeUrl: true, the coinToss would occur on the first request, and all additional requests would return the value resolved on the first request.
+
+ srcResHeaderDecorator
+
+ Decorate the inbound response headers from the proxied request.
+ router.get(
"/proxy",
proxy("www.google.com", {
srcResHeaderDecorator(headers, req, res, proxyReq, proxyRes) {
@@ -438,19 +226,11 @@ srcResHeaderDecorator
})
);
-
- filterRes(proxyRes, proxyResData) (supports Promise form)
-
-
- Allows you to inspect the proxy response, and decide if you want
- to continue processing (via oak-http-proxy) or continue onto the
- next middleware.
-
- router.get(
+
+ filterRes(proxyRes, proxyResData) (supports Promise form)
+
+ Allows you to inspect the proxy response, and decide if you want to continue processing (via oak-http-proxy) or continue onto the next middleware.
+ router.get(
"/proxy",
proxy("www.google.com", {
filterRes(proxyRes) {
@@ -459,25 +239,12 @@ filterRes(proxyRes, proxyResData) (supports Promise form)
})
);
-
- proxyErrorHandler
-
-
- By default, oak-http-proxy will throw any errors
- except ECONNRESET and ECONTIMEDOUT via
- ctx.throw(err), so that your application can handle
- or react to them, or just drop through to your default error
- handling.
-
-
- If you would like to modify this behavior, you can provide your
- own proxyErrorHandler.
-
- // Example of skipping all error handling.
+
+ proxyErrorHandler
+
+ By default, oak-http-proxy will throw any errors except ECONNRESET and ECONTIMEDOUT via ctx.throw(err), so that your application can handle or react to them, or just drop through to your default error handling.
+ If you would like to modify this behavior, you can provide your own proxyErrorHandler.
+ // Example of skipping all error handling.
app.use(
proxy("localhost:12346", {
@@ -511,19 +278,12 @@ proxyErrorHandler
})
);
-
- proxyReqUrlDecorator(url, req) (supports Promise form)
-
- Decorate the outbound proxied request url.
-
- The returned url is used for the fetch method
- internally.
-
- router.get(
+
+ proxyReqUrlDecorator(url, req) (supports Promise form)
+
+ Decorate the outbound proxied request url.
+ The returned url is used for the fetch method internally.
+ router.get(
"/proxy",
proxy("www.google.com", {
proxyReqUrlDecorator(url, req) {
@@ -534,8 +294,8 @@ proxyReqUrlDecorator(url, req) (supports Promise form)
})
);
- You can also use Promises:
- router.get(
+ You can also use Promises:
+ router.get(
"/proxy",
proxy("localhost:3000", {
proxyReqOptDecorator(url, req) {
@@ -550,37 +310,18 @@ proxyReqUrlDecorator(url, req) (supports Promise form)
})
);
-
- Generally it is advised to use the function form for the passed
- URL argument as this provides the full context object whereas the
- proxyReqOptDecorator passes only the
- context.request object.
-
-
- Potential use cases for proxyReqOptDecorator include:
-
-
- - Overriding default protocol behaviour.
- -
- Overriding default query-string and hash transfer behaviour.
-
-
-
-
- proxyReqInitDecorator(proxyReqOpts, req) (supports Promise form)
-
-
- Decorate the outbound proxied request initialization options.
-
- This configuration will be used within the
- fetch method internally to make the request to the
- provided url.
-
- router.get(
+ Generally it is advised to use the function form for the passed URL argument as this provides the full context object whereas the proxyReqOptDecorator passes only the context.request object.
+ Potential use cases for proxyReqOptDecorator include:
+
+ - Overriding default protocol behaviour.
+ - Overriding default query-string and hash transfer behaviour.
+
+
+ proxyReqInitDecorator(proxyReqOpts, req) (supports Promise form)
+
+ Decorate the outbound proxied request initialization options.
+ This configuration will be used within the fetch method internally to make the request to the provided url.
+ router.get(
"/proxy",
proxy("www.google.com", {
proxyReqInitDecorator(proxyReqOpts, srcReq) {
@@ -594,8 +335,8 @@
})
);
- You can also use Promises:
- router.get(
+ You can also use Promises:
+ router.get(
"/proxy",
proxy("www.google.com", {
proxyReqOptDecorator(proxyReqOpts, srcReq) {
@@ -608,247 +349,152 @@
})
);
-
- secure
-
-
- Normally, your proxy request will be made on the same protocol as
- the url parameter. If you'd like to force the
- proxy request to be https, use this option.
-
- app.use(
+
+ secure
+
+ Normally, your proxy request will be made on the same protocol as the url parameter. If you'd like to force the proxy request to be https, use this option.
+ app.use(
"/proxy",
proxy("http://www.google.com", {
secure: true,
})
);
-
- Note: if the proxy is passed a url without a protocol then HTTP
- will be used by default unless overridden by this option.
-
-
- preserveHostHeader
-
-
- You can copy the host HTTP header to the proxied Oak server using
- the preserveHostHeader option.
-
- router.get(
+ Note: if the proxy is passed a url without a protocol then HTTP will be used by default unless overridden by this option.
+
+ preserveHostHeader
+
+ You can copy the host HTTP header to the proxied Oak server using the preserveHostHeader option.
+ router.get(
"/proxy",
proxy("www.google.com", {
preserveHostHeader: true,
})
);
-
- parseReqBody
-
-
- The parseReqBody option allows you to control whether
- the request body should be parsed and sent with the proxied
- request. If set to false then an incoming request
- body will not be sent with the proxied request.
-
-
- reqAsBuffer
-
-
- Configure whether the proxied request body should be sent as a
- UInt8Array buffer.
-
-
- Ignored if parseReqBody is set to false.
-
- router.get(
+
+ parseReqBody
+
+ The parseReqBody option allows you to control whether the request body should be parsed and sent with the proxied request. If set to false then an incoming request body will not be sent with the proxied request.
+
+ reqAsBuffer
+
+ Configure whether the proxied request body should be sent as a UInt8Array buffer.
+ Ignored if parseReqBody is set to false.
+ router.get(
"/proxy",
proxy("www.google.com", {
reqAsBuffer: true,
})
);
-
- reqBodyEncoding
-
-
- The request body encoding to use. Currently only "utf-8"
- is supported.
-
-
- Ignored if parseReqBody is set to false.
-
- router.get(
+
+ reqBodyEncoding
+
+ The request body encoding to use. Currently only "utf-8" is supported.
+ Ignored if parseReqBody is set to false.
+ router.get(
"/post",
proxy("httpbin.org", {
reqBodyEncoding: "utf-8",
})
);
-
- reqBodyLimit
-
- The request body size limit to use.
-
- Ignored if reqBodyLimit is set to
- Infinity.
-
- router.get(
+
+ reqBodyLimit
+
+ The request body size limit to use.
+ Ignored if reqBodyLimit is set to Infinity.
+ router.get(
"/post",
proxy("httpbin.org", {
reqBodyLimit: 10_485_760, // 10MB
})
);
-
- timeout
-
- Configure a timeout in ms for the outbound proxied request.
- If not provided the request will never time out.
-
- Timed-out requests will respond with 504 status code and a
- X-Timeout-Reason header.
-
- router.get(
+
+ timeout
+
+ Configure a timeout in ms for the outbound proxied request.
+ If not provided the request will never time out.
+ Timed-out requests will respond with 504 status code and a X-Timeout-Reason header.
+ router.get(
"/",
proxy("httpbin.org", {
timeout: 2000, // in milliseconds, two seconds
})
);
-
- Contributing
-
-
-
-
- License
-
-
- oak-http-proxy is licensed under the
- MIT License.
-
-
-
-
-
-
-
-
-
- Generated using
- TypeDoc
-
-
-
-
-
-
+
+ Contributing
+
+
+
+
+ License
+
+ oak-http-proxy is licensed under the MIT License.
+