├── README.md
├── package.json
└── src
    └── index.js


/README.md:
--------------------------------------------------------------------------------
  1 | # What is KittenRouter
  2 | KittenRouter is a routing script for [Cloudflare Workers](https://www.cloudflare.com/products/cloudflare-workers/) that attempts to connect to a list of specified servers and redirect the request to whichever server that is currently 'alive' at that point of time. It is extremely useful when you have servers that may go down or are unavailable to process the request and KittenRouter can automatically attempt to redirect the request to the next configured URL for processing.
  3 | 
  4 | At the same time, it can be configured to log down information to your ElasticSearch server for analytical purposes. Some of the information logged are the status of the servers, country of the request and etc. For the full details, see the `index.js` file.
  5 | 
  6 | # How to use KittenRouter
  7 | Ultimately, KittenRouter is used together with Cloudflare workers. There are two ways in which you can use KittenRouter on your Cloudflare worker script,
  8 | 
  9 |  1. Using NPM modules
 10 |  2. Adding KittenRouter manually
 11 |  
 12 | 
 13 | ### 1) Using NPM modules
 14 | If you are comfortable in building projects in NodeJS and wanted to deploy it serverlessly on Cloudflare, you can do that as well.
 15 | 
 16 | You can use [NPM modules in Cloudflare](https://developers.cloudflare.com/workers/writing-workers/using-npm-modules/), like how we did for Inboxkitten API component, just that you will need webpack to help compact your scripts into a single `.js` file and this single `.js` file will be used in your Cloudflare worker.
 17 | 
 18 | Similarly, if you want to use KittenRouter on your Cloudflare script, you can just follow the 7 steps below to achieve it.
 19 | 
 20 | #### Step 1: Installing the necessary packages
 21 | KittenRouter is published in npm repository and you can install it as an NPM module.
 22 | ```bash
 23 |     # Change to your project directory
 24 |     $ cd <to your project>
 25 |     # Install kittenrouter
 26 |     $ npm install --save kittenrouter
 27 |     # Install webpack, we will need it to compact all your files into a single js file
 28 |     $ npm install --save webpack
 29 | ```
 30 | 
 31 | #### Step 2: Writing your code
 32 | After installing KittenRouter, you can simply create a variable and use it immediately. You can store this script as your entrypoint script such as `index.js`.
 33 | 
 34 | ```javascript
 35 |     const KittenRouter = require("kittenrouter");
 36 |     let config = {
 37 |         // some configuration that you have for your KittenRouter
 38 |     };
 39 |     let kittenrouter = new KittenRouter(confg);
 40 | 
 41 |     // Usual Cloudflare worker script
 42 |     addEventListener('fetch', event => {
 43 |         event.respondWith(handleFetchEvent(event))
 44 |     })
 45 | 
 46 |     // the async function to handle the request
 47 |     async function handleFetchEvent(event) {
 48 |         // Depends on your logic of how you want to handle the request
 49 |         // E.g. only GET requests will need to go through KittenRouter
 50 |         let req = event.request;
 51 |         if (req.method === "GET") {
 52 |             return kittenrouter.handleFetchEvent(event);
 53 |         }
 54 |         
 55 |         // Default behavior
 56 |         return await fetch(event);
 57 |     }
 58 | ```
 59 | 
 60 | #### Step 3: Setup NPM run commands
 61 | At this point, we can create a run command so that we can run it easily. In your `package.json` file, add in
 62 | ```javascript
 63 | {
 64 |     // other settings...
 65 |     "scripts": {
 66 |         // other settings...
 67 |         "build-cloudflare": "webpack --mode production index.js"
 68 |         // other settings...
 69 |     },
 70 |     // other settings...
 71 | }
 72 | ```
 73 | 
 74 | #### Step 4: Configure target environment in webpack
 75 | One thing to note in webpack is that we can specify the environment the Javascript code will be run in. `webworker` is the closest environment to Cloudflare Workers environment. So in your `webpack.config.js`, configure the target to point to `webworker`.
 76 | 
 77 | ```javascript
 78 | module.exports = {
 79 |     target: 'webworker'
 80 | };
 81 | ```
 82 | 
 83 | 
 84 | #### Step 5 (Optional): Disable minification for your webpack
 85 | In your `webpack.config.js`, add in 
 86 | ```javascript
 87 | module.exports = {
 88 |     target: 'webworker',
 89 |     optimization: {
 90 |         // We no not want to minimize our code.
 91 |         minimize: false
 92 |     }
 93 | }
 94 | ```
 95 | 
 96 | #### Step 6: Run NPM command
 97 | ```bash
 98 |     $ npm run build-cloudflare
 99 | ```
100 | 
101 | #### Step 7: Deploy to Cloudflare manually
102 | `Step 6` should create a `main.js` inside the `dist` folder, you can then copy the entire `main.js` and paste into your Cloudflare Worker's Editor of your domain.
103 | 
104 | 
105 | ### 2) Adding KittenRouter manually
106 | 
107 | #### Step 1: Your own Cloudflare worker script
108 | Given that you have a Cloudflare worker script such as 
109 | ```javascript
110 |     // Usual Cloudflare worker script
111 |     addEventListener('fetch', event => {
112 |         event.respondWith(handleFetchEvent(event))
113 |     })
114 |     
115 |     // the async function to handle the request
116 |     async function handleFetchEvent(event) {
117 |         // Default behavior
118 |         return await fetch(event);
119 |     }
120 | ```
121 | 
122 | #### Step 2: Add in the entire KittenRouter script
123 | You can then add the entire `KittenRouter` class, which is basically the `index.js` file in this github project into your script
124 | ```javascript
125 |     // methods of KittenRouter ...
126 |     // ...
127 |     class KittenRouter {
128 |         // ...
129 |     }
130 |     
131 |     // Usual Cloudflare worker script
132 |     addEventListener('fetch', event => {
133 |         event.respondWith(handleFetchEvent(event))
134 |     })
135 |     // ...
136 | ```
137 | 
138 | #### Step 3: Add in the configuration
139 | ```javascript
140 |     let config = {
141 |         // some configuration that you have for your KittenRouter
142 |     }
143 |     
144 |     // methods of KittenRouter ...
145 |     // ...
146 |     class KittenRouter {
147 |         // ...
148 |     }
149 |     
150 |     // Usual Cloudflare worker script
151 |     addEventListener('fetch', event => {
152 |         event.respondWith(handleFetchEvent(event))
153 |     })
154 |     // ...
155 | ```
156 | 
157 | #### Step 4: Use and deploy
158 | Declare the KittenRouter object and use it in your request process function. You can then deploy this script to your Cloudflare Worker.
159 | ```javascript
160 | 
161 |     let config = {
162 |         // some configuration you have for your KittenRouter
163 |     }
164 |     // methods of KittenRouter ...
165 |     // ...
166 |     class KittenRouter {
167 |         // ...
168 |     }
169 | 
170 |     // Usual Cloudflare worker script
171 |     addEventListener('fetch', event => {
172 |         event.respondWith(handleFetchEvent(event))
173 |     })
174 | 
175 |     // Initialize a new KittenRouter object
176 |     let kittenrouter = new KittenRouter(confg);
177 | 
178 |     // the async function to handle the request
179 |     async function handleFetchEvent(event) {
180 |         // Depends on your logic of how you want to handle the request
181 |         // E.g. only GET requests will need to go through KittenRouter
182 |         let req = event.request;
183 |         if (req.method === "GET") {
184 |             return kittenrouter.handleFetchEvent(event);
185 |         }
186 |         
187 |         // Default behavior
188 |         return await fetch(event);
189 |     }
190 | ```
191 | 
192 | # How to configure KittenRouter
193 | KittenRouter is initialized with a configuration map that contains the routes and log server settings attributes.
194 | 
195 | ### Configuration Map
196 | | Attribute             | Description                                                                               |
197 | |-----------------------|-------------------------------------------------------------------------------------------|
198 | | route                 | An array of servers' url for the KittenRouter to connect to. KittenRouter will attempt to access the urls in the order of the array that was set. |
199 | | log                   | A map that contains the settings for your ElasticSearch server                            |
200 | | disableOriginFallback | Set to true to disable fallback to origin host when all routes fails                      | 
201 | 
202 | A sample of the configuration map looks like this
203 | ```javascript
204 | //
205 | // Routing and logging options
206 | //
207 | module.exports = {
208 | 
209 | 	// logging endpoint to use
210 | 	log : [
211 | 		{
212 | 			// Currently only elasticsearch is supported, scoped here for future alternatives
213 | 			// One possible option is google analytics endpoint
214 | 			type : "elasticsearch",
215 | 
216 | 			//
217 | 			// Elasticsearch index endpoint 
218 | 			//
219 | 			url : "https://<Your elasticsearch server url>",
220 | 
221 | 			//
222 | 			// Authorization header (if needed)
223 | 			//
224 | 			basicAuthToken : "username:password",
225 | 
226 | 			//
227 | 			// Index prefix for storing data, this is before the "YYYY.MM" is attached
228 | 			//
229 | 			indexPrefix : "test-data-",
230 | 
231 | 			// Enable logging of the full ipv4/6
232 | 			//
233 | 			// Else it mask (by default) the last digit of IPv4 address
234 | 			// or the "network" routing for IPv6
235 | 			// see : https://www.haproxy.com/blog/ip-masking-in-haproxy/
236 | 			logTrueIP : false,
237 | 
238 | 			// @TODO support
239 | 			// Additional cookies to log
240 | 			//
241 | 			// Be careful not to log "sensitive" cookies, that can compromise security
242 | 			// typically this would be seesion keys.
243 | 			// cookies : ["__cfduid", "_ga", "_gid", "account_id"]
244 | 		}
245 | 	],
246 | 
247 | 	// Routing rules to evaluate, starting from 0 index
248 | 	// these routes will always be processed in sequence
249 | 	route : [
250 | 		// Lets load all requests to commonshost first
251 | 		"commonshost.inboxkitten.com"
252 | 
253 | 		// If it fails, we fallback to firebase
254 | 		//"firebase.inboxkitten.com"
255 | 	],
256 | 
257 | 	// Set to true to disable fallback to origin host 
258 | 	// when all routes fails
259 | 	disableOriginFallback : false,
260 | }
261 | ```
262 | 


--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "name": "kittenrouter",
 3 |   "version": "1.0.3",
 4 |   "description": "Serves as a probe to a list of configured URLs to determine if the URL is alive and retry until a 'living' URL is found or list is exhausted and fallback to original request URL",
 5 |   "main": "src/index.js",
 6 |   "scripts": {
 7 |     "test": "echo \"Error: no test specified\" && exit 1"
 8 |   },
 9 |   "repository": {
10 |     "type": "git",
11 |     "url": "git+https://github.com/uilicious/kittenrouter.git"
12 |   },
13 |   "dependencies": {},
14 |   "keywords": [
15 |     "cloudflare",
16 |     "serverless",
17 |     "router"
18 |   ],
19 |   "author": "Uilicious",
20 |   "license": "MIT",
21 |   "bugs": {
22 |     "url": "https://github.com/uilicious/kittenrouter/issues"
23 |   },
24 |   "homepage": "https://github.com/uilicious/kittenrouter#readme"
25 |   
26 | }
27 | 


--------------------------------------------------------------------------------
/src/index.js:
--------------------------------------------------------------------------------
  1 | /**
  2 |  * KittenRouter is a utility class used to 
  3 |  * 
  4 |  * - log request, for monitoring purposes (with ip masking for GDPR)
  5 |  * - reroute fetch requests an alternative "origin" endpoint
  6 |  * 	- automatically failover on request failure / timeout
  7 |  * 	- logging of failed requests
  8 |  * 	- fallback to default cloudflare "origin" endpoint
  9 |  * 
 10 |  * And as the name implies, is a sub project for InboxKitten.
 11 |  */
 12 | 
 13 | /**
 14 |  * Useful various refrence documentation, on how this whole class should be implemented
 15 |  * 
 16 |  * Cloudflare refrence documentation
 17 |  * - https://blog.cloudflare.com/logs-from-the-edge/
 18 |  * - https://developers.cloudflare.com/workers/reference/cache-api/
 19 |  * - https://blog.cloudflare.com/introducing-the-workers-cache-api-giving-you-control-over-how-your-content-is-cached/
 20 |  * - https://support.cloudflare.com/hc/en-us/articles/200170986-How-does-Cloudflare-handle-HTTP-Request-headers-
 21 |  * - https://support.cloudflare.com/hc/en-us/articles/202494830-Pseudo-IPv4-Supporting-IPv6-addresses-in-legacy-IPv4-applications
 22 |  * 
 23 |  * Webworker documentation (for fetch API)
 24 |  * - https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch
 25 |  * - https://developer.mozilla.org/en-US/docs/Web/API/Request
 26 |  * - https://developer.mozilla.org/en-US/docs/Web/API/Response
 27 |  */
 28 | 
 29 | //---------------------------------------------------------------------------------------------
 30 | //
 31 | // The following is an example config object, used to setup KittenRouter
 32 | // and kinda serve as a semi-functional spec of how KittenRouter is expected to work.
 33 | //
 34 | //---------------------------------------------------------------------------------------------
 35 | 
 36 | /*
 37 | const exampleConfig = {
 38 | 
 39 | 	// logging endpoint to use
 40 | 	log : [
 41 | 		{
 42 | 			// Currently only elasticsearch is supported, scoped here for future alternatives
 43 | 			// One possible option is google analytics endpoint
 44 | 			type : "elasticsearch",
 45 | 
 46 | 			//
 47 | 			// Elasticsearch index endpoint 
 48 | 			//
 49 | 			url : "https://elasticsearch-server.secret-domain.com/",
 50 | 
 51 | 			//
 52 | 			// Authorization header (if needed)
 53 | 			//
 54 | 			authUser : "user",
 55 | 			authPass : "pass",
 56 | 
 57 | 			//
 58 | 			// Index prefix for storing data, this is before the "YYYY.MM" is attached
 59 | 			//
 60 | 			indexPrefix : "test-data-",
 61 | 
 62 | 			// Enable logging of the full ipv4/6
 63 | 			//
 64 | 			// Else it mask (by default) the last digit of IPv4 address
 65 | 			// or the "network" routing for IPv6
 66 | 			// see : https://www.haproxy.com/blog/ip-masking-in-haproxy/
 67 | 			logTrueIP : false,
 68 | 
 69 | 			// @TODO support
 70 | 			// Additional cookies to log
 71 | 			//
 72 | 			// Be careful not to log "sensitive" cookies, that can compromise security
 73 | 			// typically this would be seesion keys.
 74 | 			// cookies : ["__cfduid", "_ga", "_gid", "account_id"]
 75 | 		}
 76 | 	],
 77 | 
 78 | 	// Routing rules to evaluate, starting from 0 index
 79 | 	// these routes will always be processed in sequence
 80 | 	route : [
 81 | 
 82 | 		// Lets load all requests to commonshost first
 83 | 		"commonshost.inboxkitten.com",
 84 | 
 85 | 		// If it fails, we fallback to firebase
 86 | 		"firebase.inboxkitten.com"
 87 | 
 88 | 		// // Object based route definitions
 89 | 		// // THE FOLLOWING BELOW IS NOT SUPPORTED AS OF NOW!!!
 90 | 		// //-----------------------------------------------------------------
 91 | 		// {
 92 | 		// 	// "" host routing will match all
 93 | 		// 	reqHost : [""],
 94 | 		// 	// Routing prefix to check for, note that "" will match all
 95 | 		// 	reqPrefix : [""],
 96 | 		//
 97 | 		// 	// Origin servers to route to
 98 | 		// 	host : "host-endpoint-c",
 99 | 		// 	port : 443,
100 | 		// 	protocol : "https",
101 | 		// 	// Matching by country
102 | 		// 	// Country codes : https://support.cloudflare.com/hc/en-us/articles/205072537-What-are-the-two-letter-country-codes-for-the-Access-Rules-
103 | 		// 	country : [
104 | 		// 		"SG"
105 | 		// 	],
106 | 		// 	// Matching by region
107 | 		// 	region : [
108 | 		// 		"Europe"
109 | 		// 	],
110 | 		// 	// Timeout to abort request on
111 | 		// 	timeout : 2000,
112 | 		//
113 | 		// 	// Fetching sub options (like cache overwrite)
114 | 		// 	// Cloudflare fetch config https://developers.cloudflare.com/workers/reference/cloudflare-features/
115 | 		// 	fetchConfig : { cf: { cacheEverything: true } }
116 | 	
117 | 		// 	// @TODO (consider support for nested object based origin decleration?)
118 | 		// 	// Might be useful for some region based routing or maybe crazier?
119 | 		// 	// Racing origin requests and terminating the "slower copy"
120 | 		// 	//-------------------------------------------------------------------------
121 | 		// }
122 | 	],
123 | 
124 | 	// Set to true to disable fallback to origin host 
125 | 	// when all routes fails
126 | 	disableOriginFallback : false,
127 | 
128 | 	// Support default timeout to process a request in milliseconds
129 | 	defaultRouteTimeout : 2000, // 2,000 ms = 2 s
130 | 
131 | 	// Support for cloudflare caching 
132 | 	disableCloudflarePreRouteCache : false,
133 | 
134 | 	// @TODO crazier caching options to consider
135 | 	// - KeyValue caching (probably pointless, cost wise)
136 | 	// - In memory caching (with a limit of 500 objects + 10 kb per object?)
137 | 	// See : https://developers.cloudflare.com/workers/writing-workers/storing-data/
138 | }
139 | */
140 | 
141 | //---------------------------------------------------------------------------------------------
142 | //
143 | // Logging internal logic
144 | //
145 | //---------------------------------------------------------------------------------------------
146 | 
147 | // Generate a random uuid to identify the instance
148 | let workerID = Math.random().toString(36).substring(2, 15) + Math.random().toString(36).substring(2, 15);
149 | let reqCount = 0;
150 | 
151 | // Simple regex to validate for an ipv4
152 | const ipv4_simpleRegex = /^[0-9a-z]{1,3}\.[0-9a-z]{1,3}\.[0-9a-z]{1,3}\.[0-9a-z]{1,3}$/i;
153 | 
154 | /**
155 |  * Extract from a request, various possible ip properties (in cludflare) 
156 |  * for a valid ipv4 address
157 |  * 
158 |  * @param {Request} request object to extract from
159 |  * @param {Boolean} logTrueIP (defaul false) used to log unmasked ip if true
160 |  * 
161 |  * @return {String} ipv4 string if found, else a blank string of ""
162 |  */
163 | function getIPV4(request, logTrueIP = false) {
164 | 	let headers = request.headers;
165 | 	let ip = headers.get('cf-pseudo-ipv4') || headers.get('cf-connecting-ipv4') || headers.get('cf-connecting-ip') || '';
166 | 	ip = ip.trim();
167 | 
168 | 	// If ipv4 validation failed, return blank
169 | 	if(ip === '' || !ipv4_simpleRegex.test(ip)) {
170 | 		return "";
171 | 	}
172 | 
173 | 	// Assume that its a valid ipv4
174 | 	// return immediately if no ipmasking is done
175 | 	if(logTrueIP == false) {
176 | 		return ip;
177 | 	}
178 | 
179 | 	// Time to perform ip masking
180 | 	let ip_split = ip.split(".");
181 | 	ip_split[3] = "xxx";
182 | 	return ip_split.join(".");
183 | }
184 | 
185 | /**
186 |  * Extract from a request, various possible ip properties (in cludflare) 
187 |  * for a valid ipv6 address
188 |  * 
189 |  * @param {Request} request object to extract from
190 |  * @param {Boolean} logTrueIP (defaul false) used to log unmasked ip if true
191 |  * 
192 |  * @return {String} ipv6 string if found, else a blank string of ""
193 |  */
194 | function getIPV6(request, logTrueIP = false) {
195 | 	let headers = request.headers;
196 | 	let ip = headers.get('cf-connecting-ipv6') || headers.get('cf-connecting-ip') || '';
197 | 	ip = ip.trim();
198 | 
199 | 	// If ipv4 validation passes, return blank
200 | 	if(ip === '' || ipv4_simpleRegex.test(ip)) {
201 | 		return "";
202 | 	}
203 | 
204 | 	// Assume that its an ipv6
205 | 	// return immediately if no ipmasking is done
206 | 	if(logTrueIP == false) {
207 | 		return ip;
208 | 	}
209 | 
210 | 	// Time to perform ip masking
211 | 	let ip_split = ip.split(":");
212 | 	for(let i=2; i<ip_split.length; ++i) {
213 | 		ip_split[i] = "xxxx"
214 | 	}
215 | 	return ip_split.join(":");
216 | }
217 | 
218 | // Log request with a single config map
219 | async function logRequestWithConfigMap(logConfig, request, response, routeType, routeCount, currentRequestCount) {
220 | 	// Does nothing if logconfig is null
221 | 	if( logConfig == null || logConfig.url == null || logConfig.url.length <= 0 ) {
222 | 		return null;
223 | 	}
224 | 
225 | 	// Index YYYY.MM formating
226 | 	let indexYearAndMonth = (new Date()).toISOString().substr(0,7).replace("-",".");
227 | 	let indexPrefix = logConfig.indexPrefix || "KittenRouter-log-";
228 | 
229 | 	// The full POST request URL
230 | 	let fullLoggingURL = logConfig.url.trim();
231 | 	if( !fullLoggingURL.endsWith("/") ) {
232 | 		fullLoggingURL = fullLoggingURL+"/";
233 | 	}
234 | 	fullLoggingURL = fullLoggingURL+logConfig.indexPrefix+indexYearAndMonth+"/_doc/";
235 | 
236 | 	// Trueip logging flag
237 | 	let logTrueIP = logConfig.logTrueIP || false;
238 | 
239 | 	// The data to log
240 | 	let data = {
241 | 		'timestamp': (new Date()).toISOString(),
242 | 
243 | 		'route.type':  routeType,
244 | 		'route.count': routeCount,
245 | 
246 | 		'req.url':        request.url,
247 | 		'req.referer':    request.referrer || '',
248 | 		'req.method':     request.method,
249 | 
250 | 		'req.ipv4':          getIPV4(request, logTrueIP),
251 | 		'req.ipv6':          getIPV6(request, logTrueIP),
252 | 		'req.host':          request.headers.get('host') || '',
253 | 		'req.user-agent':    request.headers.get('user-agent') || '',
254 | 		'req.country-code':  request.headers.get('cf-ipcountry') || '',
255 | 
256 | 		'req.cf.ray':     request.headers.get('cf-ray') || '',
257 | 		'req.cf.colo':    (request.cf && request.cf.colo) || '',
258 | 		'req.tlsVersion': (request.cf && request.cf.tlsVersion) || '',
259 | 		'req.tlsCipher':  (request.cf && request.cf.tlsCipher) || '',
260 | 
261 | 		'res.status':           response.status,
262 | 		'res.url':              response.url,
263 | 		'res.server':           response.headers.get('server') || '',
264 | 		'res.via':              response.headers.get('via') || '',
265 | 		'res.content-type':     response.headers.get('content-type') || '',
266 | 		'res.content-encoding': response.headers.get('content-encoding') || '',
267 | 		'res.content-length':   response.headers.get('content-length') || '',
268 | 		'res.cache-control':    response.headers.get('cache-control') || '',
269 | 		'res.cf.cache-status':  response.headers.get('cf-cache-status') || '',
270 | 		'res.cf.ray':           response.headers.get('cf-ray') || '',
271 | 
272 | 		// Additional information related to this worker
273 | 		'worker.id':            workerID, // currently the workerID is tagged to the cf-ray of cloudflare request.headers['cf-ray']
274 | 		'worker.reqCount':      currentRequestCount, // currentRequestCount refers to the number of times this instance was called.
275 | 
276 | 		'config.logTrueIP': logTrueIP
277 | 	};
278 | 
279 | 	// // Cookies to log
280 | 	// let cookieNames = logConfig.cookies;
281 | 	// if( cookieNames != null && cookieNames.length > 0 ) {
282 | 	// 	let cookieJar = request.headers.get("Cookie")
283 | 	// 	// @TODO : iterate cookies and log relevent keys
284 | 	// }
285 | 
286 | 	// Lets prepare the headers
287 | 	let logHeaders = {
288 | 		'Content-Type': 'application/json',
289 | 	};
290 | 
291 | 	// Lets handle authentication
292 | 	if( logConfig.basicAuthToken && logConfig.basicAuthToken.length > 0 ) {
293 | 		logHeaders["Authorization"] = "Basic "+btoa(logConfig.basicAuthToken);
294 | 	}
295 | 
296 | 	// The elasticsearch POST request to perform for logging
297 | 	let logResult = await fetch(
298 | 		fullLoggingURL, {
299 | 		method: 'POST',
300 | 		body: JSON.stringify(data),
301 | 		headers: new Headers(logHeaders)
302 | 	})
303 | 
304 | 	// Log the log?
305 | 	if( logConfig.consoleDebug ) {
306 | 		console.log("KittenRouter logging response", logResult);
307 | 	}
308 | 
309 | 	// Return the result
310 | 	return logResult;
311 | }
312 | 
313 | // Log request with a config array
314 | async function logRequestWithConfigArray(configArr, request, response, routeType, routeCount, currentRequestCount) {
315 | 	// Does nothing if configArr is null
316 | 	if( configArr == null || configArr.length <= 0 ) {
317 | 		return null;
318 | 	}
319 | 
320 | 	// Lets iterate the config
321 | 	let promiseArray = [];
322 | 	for(let i=0; i<configArr.length; ++i) {
323 | 		promiseArray[i] = logRequestWithConfigMap(configArr[i], request, response, routeType, routeCount, currentRequestCount);
324 | 	}
325 | 
326 | 	// Return with a single promise object
327 | 	return Promise.all(promiseArray);
328 | }
329 | 
330 | //---------------------------------------------------------------------------------------------
331 | //
332 | // Utility functions
333 | //
334 | //---------------------------------------------------------------------------------------------
335 | 
336 | /**
337 |  * Clones a URL object, with an origin string
338 |  * 
339 |  * @param {URL} inURL to clone over
340 |  * @param {String} originHostStr to overwrite host with
341 |  * 
342 |  * @return {URL} cloned URL object with new origin host
343 |  */
344 | function cloneUrlWithNewOriginHostString(inURL, originHostStr) {
345 | 	let ret = new URL(inURL);
346 | 	ret.host = originHostStr;
347 | 	return ret;
348 | }
349 | 
350 | /**
351 |  * Generate a Response object, containing an error
352 |  * @param {String} errorCode for the error
353 |  * @param {String} errorMsg containing error details
354 |  * @param {int} httpCode (default=500) for response object 
355 |  */
356 | function setupResponseError(errorCode, errorMsg, httpCode = 500) {
357 | 	let ret = new Response(
358 | 		JSON.stringify({
359 | 			error: {
360 | 				code : errorCode,
361 | 				message : errorMsg
362 | 			}
363 | 		}),
364 | 		{ 
365 | 			status: httpCode, 
366 | 			statusText: errorCode, 
367 | 			headers: {
368 | 				"Content-Type": "application/json",
369 | 				//"KittenRouterException": "true"
370 | 			}
371 | 		}
372 | 	);
373 | 	ret._isKittenRouterException = true;
374 | 	return ret;
375 | }
376 | 
377 | /**
378 |  * Lets do a oversimplified check if a response object is valid
379 |  * if the response code is 200~399
380 |  * 
381 |  * @param {*} resObj 
382 |  * 
383 |  * @return true if its a valid response object
384 |  */
385 | function isGoodResponseObject(resObj) {
386 | 	return resObj != null && resObj.status >= 200 && resObj.status < 400;
387 | }
388 | 
389 | /**
390 |  * Check if the given response object is a KittenRouter exception
391 |  * @param {Response} resObj to validate
392 |  * 
393 |  * @return true if its a KittenRouter exception 
394 |  */
395 | function isKittenRouterException(resObj) {
396 | 	return resObj != null && resObj._isKittenRouterException;
397 | 	// resObj.headers && resObj.headers.get("KittenRouterException") == "true";
398 | }
399 | 
400 | const fetchOptionsKey = [
401 | 	"method",
402 | 	"headers",
403 | 	"body",
404 | 	"mode",
405 | 	"credentials",
406 | 	"cache",
407 | 	"redirect",
408 | 	"referrer",
409 | 	"referrerPolicy",
410 | 	"integrity",
411 | 	"keepalive",
412 | 	"signal"
413 | ];
414 | 
415 | const overwriteFetchOptionsKey = [
416 | 	"method",
417 | 	// "headers",
418 | 	// "body",
419 | 	"mode",
420 | 	"credentials",
421 | 	"cache",
422 | 	"redirect",
423 | 	"referrer",
424 | 	"referrerPolicy",
425 | 	"integrity",
426 | 	"keepalive",
427 | 	"signal",
428 | 	"cf" // cloudflare custom settings
429 | ]
430 | 
431 | /**
432 |  * To extend and include additional configuration options into the original
433 |  * fetchOptions
434 |  * 
435 |  * Currently only extension of headers are supported
436 |  * 
437 |  * @param {*} fetchOptions object to be clone
438 |  * @param {*} extendHeaders that contains the attributes to be replaced
439 |  * 
440 |  * @return cloneExtendedFetchOptions, cloning the original fetch options with extended fetch options
441 |  */
442 | function cloneAndExtendFetchOptions(fetchOptions, extendOptions){
443 | 	// Init a new fetch options
444 | 	let ret = {}
445 | 	
446 | 	// Clone all keys inside fetch options
447 | 	for(let i=0; i < fetchOptionsKey.length; ++i){
448 | 		let key = fetchOptionsKey[i]
449 | 		try {
450 | 			// Why try catch, and ignore here!!!
451 | 			//
452 | 			// Well it seems like some properties of a request object
453 | 			// cannot be safely checked for "if not null", without
454 | 			// an error. Hence this work around. Sad =()
455 | 			if( fetchOptions[key] != null ) {
456 | 				ret[key] = fetchOptions[key]
457 | 			}
458 | 		} catch(e) {
459 | 			// does nothing : hopefully someone can do a better if != null ?
460 | 		}
461 | 	}
462 | 
463 | 	// Clone over all the overwriting options (if applicable)
464 | 	for(let i=0; i < overwriteFetchOptionsKey.length; ++i) {
465 | 		let key = overwriteFetchOptionsKey[i]
466 | 		if(extendOptions[key] !== null) {
467 | 			ret[key] = extendOptions[key]
468 | 		}
469 | 	}
470 | 
471 | 	// Overwrite the headers if needed
472 | 	if(extendOptions["overwriteHeaders"] !== null) {
473 | 		ret.headers = Object.assign({}, extendOptions["overwriteHeaders"]);
474 | 	}
475 | 
476 | 	// Lets get the headers to extend
477 | 	let extendHeaders = extendOptions["headers"];
478 | 	if(extendHeaders !== null) {
479 | 		let newHeaders = ret.headers || {};
480 | 		// For all the headers that needs to be overwritten, overwrite if it exists
481 | 		for (key in extendHeaders){
482 | 			newHeaders[key] = extendHeaders[key]
483 | 		}
484 | 		ret.headers = newHeaders
485 | 	}
486 | 
487 | 	// Function overwrites
488 | 	if( extendOptions["optionsFunction"] != null ) {
489 | 		extendOptions["optionsFunction"](ret, fetchOptions, extendOptions);
490 | 	} 
491 | 
492 | 	// Return back a cloned extended fetch options
493 | 	return ret
494 | }
495 | 
496 | 
497 | 
498 | /**
499 |  * Calling of fetch, with a timeout option which returns an error instead
500 |  * See: https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch
501 |  * 
502 |  * @param {*} resource 
503 |  * @param {*} init 
504 |  * @param {Integer} timeout in approximate milliseconds to return a failure
505 |  * 
506 |  * @return {Response} object of the request
507 |  */
508 | function fetchWithTimeout(resource, init, timeout = 2000) {
509 | 	// Calling the fetch request
510 | 	let fetchPromise = fetch(resource, init);
511 | 
512 | 	// Timeout promise
513 | 	let timeoutPromise = new Promise(function(good,bad) {
514 | 		setTimeout(function() {
515 | 			good( setupResponseError("ROUTE_TIMEOUT", "Route failed due to timeout : "+timeout+" ms") );
516 | 		}, timeout);
517 | 	});
518 | 	
519 | 	// Return a racing promise
520 | 	return Promise.race([ fetchPromise, timeoutPromise ]);
521 | }
522 | 
523 | //---------------------------------------------------------------------------------------------
524 | //
525 | // Cloudflare Caching logic
526 | //
527 | //---------------------------------------------------------------------------------------------
528 | 
529 | // Cloudflare constant prerouting cache
530 | const preRouteCache = caches.default;
531 | 
532 | /**
533 |  * Returned cached response (if valid)
534 |  * @param {Request} inRequest to use as key
535 |  */
536 | async function matchPrerouteCache(inRequest) {
537 | 	return preRouteCache.match(inRequest);
538 | }
539 | 
540 | /**
541 |  * Fill up the cloudflare cache, with a response object.
542 |  * This will automaticaly handle the response expirary rules
543 |  * 
544 |  * @param {Request} inRequest to use as key
545 |  * @param {Response} outResponse to cach
546 |  * @param {Boolean} enable (default true), configure to false to skip route cache fill
547 |  * 
548 |  * @return the outResponse (to pass upwards)
549 |  */
550 | async function fillupPrerouteCache(inRequest, outResponse, enable = true) {
551 | 	if(enable) {
552 | 		preRouteCache.put(inRequest, outResponse.clone());
553 | 	}
554 | 	return outResponse;
555 | }
556 | 
557 | //---------------------------------------------------------------------------------------------
558 | //
559 | // Routing internal logic
560 | //
561 | //---------------------------------------------------------------------------------------------
562 | 
563 | /**
564 |  * Makes a request, with a different origin host
565 |  * 
566 |  * @param {String} originHostStr to overwrite host with
567 |  * @param {Request} inRequest to use 
568 |  * @param {Integer} defaultRouteTimeout in approximate milliseconds to return a failure
569 |  * 
570 |  * @return {Response} object of the request
571 |  */
572 | // Process a routing request, and return its response object
573 | async function processOriginRoutingStr(originHostStr, inRequest, defaultRouteTimeout = 2000) {
574 | 	return fetchWithTimeout( //
575 | 		cloneUrlWithNewOriginHostString(inRequest.url,originHostStr), //
576 | 		inRequest, //
577 | 		defaultRouteTimeout
578 | 	);
579 | }
580 | 
581 | /**
582 |  * Makes a request, with a different origin host configured by an object
583 |  * 
584 |  * @param {Object} originObj to overwrite host with
585 |  * @param {Request} inRequest to use 
586 |  * @param {Integer} defaultRouteTimeout in approximate milliseconds to return a failure
587 |  * 
588 |  * @return {Response} object of the request
589 |  */
590 | async function processOriginRoutingObj(originObj, inRequest, defaultRouteTimeout = 2000) {
591 | 	return fetchWithTimeout(
592 | 		cloneUrlWithNewOriginHostString(inRequest.url, originObj.host), //
593 | 		cloneAndExtendFetchOptions(inRequest, originObj), //
594 | 		originObj.timeout || defaultRouteTimeout
595 | 	)
596 | }
597 | 
598 | // // Process a routing request, and return its response object
599 | // async function processOriginRouting(origin, inRequest) {
600 | // 	if( (typeof origin) === "string" ) {
601 | // 		return processOriginRoutingStr(origin, inRequest);
602 | // 	}
603 | // 	throw "Object based routing config is NOT yet supported";
604 | // }
605 | 
606 | /**
607 |  * Process a request, and perform the required route request and logging
608 |  * This DOES NOT handle the fetch fallback
609 |  * 
610 |  * @param {Object} configObj conataining both the .route, and .log array config
611 |  * @param {*} fetchEvent provided from cloudflare, attaches logging waitUntil
612 |  * @param {Request} inRequest to process 
613 |  * @param {int} currentRequestCount that keep tracks of how many requests have been made to this instance
614 |  * 
615 |  * @return {Response} if a valid route with result is found, else return final route request failure (if any), else return null
616 |  */
617 | async function processRoutingRequest( configObj, fetchEvent, inRequest, currentRequestCount ) {
618 | 	// Lets get the route, and log array first
619 | 	let routeArray = configObj.route;
620 | 	let logArray = configObj.log;
621 | 	let defaultRouteTimeout = configObj.defaultRouteTimeout || 2000;
622 | 
623 | 	// Return null, on empty routeArray
624 | 	if( routeArray == null || routeArray.length <= 0 ) {
625 | 		return null;
626 | 	}
627 | 
628 | 	// setup the variable for response object
629 | 	let resObj = null;
630 | 
631 | 	// Lets iterate the routes
632 | 	for( let i=0; i<routeArray.length; ++i ) {
633 | 		let route = routeArray[i];
634 | 
635 | 		// Route string processing
636 | 		if( (typeof route) === "string" ) {
637 | 			// Lets handle string origins
638 | 			resObj = await processOriginRoutingStr( route, inRequest, defaultRouteTimeout );
639 | 
640 | 			// Lets log 
641 | 			fetchEvent.waitUntil( logRequestWithConfigArray( logArray, inRequest, resObj, "ROUTE_REQUEST", i, currentRequestCount ) );
642 | 
643 | 			// If its a valid response, return it
644 | 			if( isGoodResponseObject(resObj) ) {
645 | 				return resObj;
646 | 			}
647 | 
648 | 			// Lets continue to next route
649 | 			continue;
650 | 		} else {
651 | 			// Lets handle object origins
652 | 			resObj = await processOriginRoutingObj( route, inRequest, defaultRouteTimeout );
653 | 
654 | 			// Lets log 
655 | 			fetchEvent.waitUntil( logRequestWithConfigArray( logArray, inRequest, resObj, "ROUTE_REQUEST", i, currentRequestCount ) );
656 | 
657 | 			// If its a valid response, return it
658 | 			if( isGoodResponseObject(resObj) ) {
659 | 				return resObj;
660 | 			}
661 | 
662 | 			// Lets continue to next route
663 | 			continue;
664 | 		}
665 | 
666 | 		// Throw an exception on an unknown route type
667 | 		return setupResponseError("UNKNOWN_CONFIG", "Object based route config is not yet supported");
668 | 	}
669 | 
670 | 	return resObj;
671 | }
672 | 
673 | /**
674 |  * Process the fetch event as it comes from cloudflare
675 |  * 
676 |  * @param {Object} configObj for the KittenRouter.config
677 |  * @param {*} fetchEvent provided from cloudflare
678 |  * 
679 |  * @return {Response} if a valid route with result is found, else the last route error (if applicable)
680 |  */
681 | async function processFetchEvent( configObj, fetchEvent ) {
682 | 	// Lets unpack out the request
683 | 	let inReq = fetchEvent.request;
684 | 	let resObj = null;
685 | 
686 | 	// Lets get pre route caching config
687 | 	let disableCloudflarePreRouteCache = configObj.disableCloudflarePreRouteCache || false;
688 | 	let enableCloudflarePreRouteCache = !disableCloudflarePreRouteCache;
689 | 
690 | 	// Lets safely get the request count with an increment
691 | 	let currentRequestCount = ++reqCount;
692 | 
693 | 	// Lets check the local cache
694 | 	//----------------------------------------------------------------------
695 | 
696 | 	if( enableCloudflarePreRouteCache ) {
697 | 		resObj = await matchPrerouteCache(inReq);
698 | 		if( resObj != null ) {
699 | 			// Cache found, log down the details before returning the response
700 | 			let routeArray = configObj.route;
701 | 			let logArray = configObj.log;
702 | 			fetchEvent.waitUntil( logRequestWithConfigArray( logArray, inReq, resObj, "PREROUTE_MATCHED_REQUEST", -1, currentRequestCount ) );
703 | 			// Cache found, returns
704 | 			return resObj;
705 | 		}
706 | 		// Cache matching fail, go fetch it
707 | 	}
708 | 
709 | 	// Lets process the routing request
710 | 	//----------------------------------------------------------------------
711 | 
712 | 	// Lets try to get a response from a route
713 | 	resObj = await processRoutingRequest( configObj, fetchEvent, inReq, currentRequestCount );
714 | 
715 | 	// Lets return the response object if its valid
716 | 	// We do an oversimilified assumption that its valid 
717 | 	// if the response code is 200~399
718 | 	if( isGoodResponseObject(resObj) ) {
719 | 		// Cache (if enabled) preroute, and return
720 | 		return fillupPrerouteCache(inReq, resObj, enableCloudflarePreRouteCache);
721 | 	}
722 | 
723 | 	// Throw and show results from setupResponseError (for direct feedback loop)
724 | 	if( isKittenRouterException(resObj) ) {
725 | 		// We do not cache exceptions
726 | 		return resObj;
727 | 	}
728 | 
729 | 	// At this point all routes are assumed to have failed
730 | 	// As such we will attempt to do a fallback to the default origin
731 | 	//----------------------------------------------------------------------
732 | 
733 | 	// Origin fallback disabled, return last response, or a hard error
734 | 	if( configObj.disableOriginFallback ) {
735 | 		// No response object returned by routes : assume no valid routes
736 | 		if( resObj == null ) {
737 | 			// We do not cache exceptions
738 | 			return setupResponseError("NO_VALID_ROUTE", "No valid route found in config");
739 | 		}
740 | 
741 | 		// Else return the last failed route response
742 | 		// We do not cache exceptions
743 | 		return resObj;
744 | 	}
745 | 
746 | 	// Lets fetch the cloudflare origin request, log it, and return its result instead
747 | 	resObj = await fetch(inReq);
748 | 	fetchEvent.waitUntil( logRequestWithConfigArray( configObj.log, inReq, resObj, "ORIGIN_FALLBACK", -1, currentRequestCount ) );
749 | 
750 | 	// Cache (if enabled) preroute, and return
751 | 	return fillupPrerouteCache(inReq, resObj, enableCloudflarePreRouteCache);
752 | }
753 | 
754 | //---------------------------------------------------------------------------------------------
755 | //
756 | // Class implementation (and public interface)
757 | //
758 | //---------------------------------------------------------------------------------------------
759 | 
760 | class KittenRouter {
761 | 	
762 | 	/**
763 | 	 * Setup KittenRouter instance with the given config
764 | 	 * 
765 | 	 * @param inConfig for configuring KittenRouter
766 | 	 */
767 | 	constructor(inConfig) {
768 | 		this.config = inConfig || {}; // fallback for blank object (make certain things easier)
769 | 	}
770 | 
771 | 	/**
772 | 	 * Request handling function, and routing
773 | 	 * 
774 | 	 * @param  fetchEvent from cloudflare to process
775 | 	 * 
776 | 	 * @return response object for cloudflare
777 | 	 */
778 | 	async handleFetchEvent(fetchEvent) {
779 | 		return await processFetchEvent(this.config, fetchEvent);
780 | 	}
781 | }
782 | 
783 | //---------------------------------------------------------------------------------------------
784 | //
785 | // !!! STOP HERE !!! If your copy and pasting the above, directly to cloudflare
786 | //                   do not copy the lines below
787 | //
788 | //---------------------------------------------------------------------------------------------
789 | 
790 | // Export out the KittenRouter class, if possible
791 | // Skipped if used directly in cloudflare worker
792 | module.exports = KittenRouter;
793 | 
794 | //---------------------------------------------------------------------------------------------
795 | //
796 | // Quick and dirty sample implementation (for cloudflare debugging)
797 | //
798 | //---------------------------------------------------------------------------------------------
799 | 
800 | /*
801 | //
802 | // If module does not exist, this is probably a cloudflare debugging session
803 | // Lets do this =)
804 | //
805 | 
806 | // KittenRouter setup
807 | const router = new KittenRouter({
808 | 
809 | 	// logging endpoint to use
810 | 	log : [
811 | 		{
812 | 			// Currently only elasticsearch is supported, scoped here for future alternatives
813 | 			// One possible option is google analytics endpoint
814 | 			type : "elasticsearch",
815 | 
816 | 			//
817 | 			// Elasticsearch index endpoint 
818 | 			//
819 | 			url : "https://inboxkitten.logging.com/",
820 | 
821 | 			//
822 | 			// Authorization header (if needed)
823 | 			//
824 | 			basicAuthToken : "elasticsearch:password",
825 | 
826 | 			//
827 | 			// Index prefix for storing data, this is before the "YYYY.MM" is attached
828 | 			//
829 | 			indexPrefix : "test-data-",
830 | 
831 | 			// Enable logging of the full ipv4/6
832 | 			//
833 | 			// Else it mask (by default) the last digit of IPv4 address
834 | 			// or the "network" routing for IPv6
835 | 			// see : https://www.haproxy.com/blog/ip-masking-in-haproxy/
836 | 			logTrueIP : false,
837 | 
838 | 			// @TODO support
839 | 			// Additional cookies to log
840 | 			//
841 | 			// Be careful not to log "sensitive" cookies, that can compromise security
842 | 			// typically this would be seesion keys.
843 | 			// cookies : ["__cfduid", "_ga", "_gid", "account_id"]
844 | 		}
845 | 	],
846 | 
847 | 	route: [
848 | 		{
849 | 			host:"commonshost.inboxkitten.com",
850 | 			headers : {
851 | 				"X-Forwarded-Host": "inboxkitten.com",
852 | 				"X-Forwarded-Proto": "https"
853 | 			}
854 | 		},
855 | 		"commonshost.inboxkitten.com",
856 | 		"firebase.inboxkitten.com"
857 | 	]
858 | });
859 | 
860 | // Cloudflare fetch result handling
861 | addEventListener('fetch', event => {
862 | 	event.respondWith(router.handleFetchEvent(event))
863 | });
864 | */
865 | 


--------------------------------------------------------------------------------