Firefox add-on that functions as a light-weight (pseudo) rules-engine for easily modifying HTTP headers in either direction
2+ hour long screencast that is a detailed walk-through of installation, configuration and usage
//
new RegExp('')
both requests and responses
request.window_location
= {}href
: [string] full URIprotocol
: [string]http:
https:
file:
username
: [string]password
: [string]host
: [string]port
: [string]path
: [string]query
: [string]hash
: [string]file_ext
: [string]request.uri
= {}
same keys as:
request.window_location
request.original_uri
= {}
same keys as:
request.window_location
request.referrer
= {}
same keys as:
request.window_location
request.method
[string]request.headers
= {}request.headers.unmodified
= {}request.headers.updated
= {}string
value will set/update the HTTP header corresponding to its hash key.boolean
false value will be ignored.request only
response only
response.headers
= {}response.headers.unmodified
= {}response.headers.updated
= {}
hash of all HTTP headers that the rules array data set (for responses) has incrementally modified at the current point of rules processing.
see additional notes under:
request.headers.updated
response.status_code
[integer]response.charset
[string]response.content_length
[integer]response.content_type
[string]always available
atob(string_base64_encoded)
decodes a string of data which has been encoded using base-64 encoding.
base64_decode(string_base64_encoded)
alias for:
atob
btoa(string_value)
creates a base-64 encoded ASCII string from a "string" of binary data.
base64_encode(string_value)
alias for:
btoa
md2(string_value)
returns the result of hashing the input string using the md2
crypto hash function
md5(string_value)
returns the result of hashing the input string using the md5
crypto hash function
sha1(string_value)
returns the result of hashing the input string using the sha1
crypto hash function
sha256(string_value)
returns the result of hashing the input string using the sha256
crypto hash function
sha384(string_value)
returns the result of hashing the input string using the sha384
crypto hash function
sha512(string_value)
returns the result of hashing the input string using the sha512
crypto hash function
format_date(Date | parsable_date_string)
returns the date as a UTC formatted string
format_date(null, 1)
returns the current date as a UTC formatted string
log()
for all usage patterns, refer to docs
helpful tip: configure the javascript console to "enable persistent logs"
both requests and responses
save()
Output File
.request only
redirectTo(string_URI)
HTTP redirection works for any matching request URL.
When the matching request URL is the top-level page loading in a browser tab,
window.location = string_URI
When the matching request URL is a page resource that's referenced by a top-level page loading in a browser tab,
For an example of top-level page redirection,
check out the recipe: redirect search engine queries from Yahoo to Google
For an example that illustrates both top-level as well as resource redirection,
check out the recipe: redirect Google favicon
cancel()
completely cancels the HTTP request.
For an example,
check out the recipe: light weight ad-blocker
response only
each rule can have the following attributes:
url
(required, RegExp
)headers
(required, object
or function
):stop
(optional, boolean
or function
):url
pattern of this rule matches the requested URL, andthen:
url
pattern match occurs for a rule,headers
or stop
attribute of the matching rule object is declared as a javascript function:
[
/* ****************************************************
* all requests: add 3 custom headers
* ****************************************************
*/
{
"url" : /^.*$/,
"headers" : {
"X-Custom-Sample-Header-01" : "Foo",
"X-Custom-Sample-Header-02" : "Bar",
"X-Custom-Sample-Header-03" : "Baz"
}
},
/* ****************************************************
* secure requests: cancel the 3 custom headers, and stop processing rules
* ****************************************************
*/
{
"url" : /^https/i,
"headers" : {
"X-Custom-Sample-Header-01" : false,
"X-Custom-Sample-Header-02" : false,
"X-Custom-Sample-Header-03" : false
},
"stop": true
},
/* ****************************************************
* all requests: update 1st custom header, cancel 3rd custom header
* ****************************************************
*/
{
"url" : /^.*$/,
"headers" : {
"X-Custom-Sample-Header-01" : "Hello",
"X-Custom-Sample-Header-03" : false
}
}
/* ****************************************************
* assertion #1: non-secure URL request
* expected result:
* X-Custom-Sample-Header-01: Hello
* X-Custom-Sample-Header-02: Bar
* ****************************************************
*/
]
[
/* ****************************************************
* purpose: map an applicable 'content-type' to a finite set of resources
* as identified by file extension, when loaded from local hard disk.
* ****************************************************
*/
{
"url" : new RegExp('^file://', 'i'),
"headers" : function(){
var $headers = {};
switch( request.uri.file_ext.toLowerCase() ){
case 'txt':
$headers['content-type'] = 'text/plain';
break;
case 'css':
$headers['content-type'] = 'text/css';
break;
case 'js':
$headers['content-type'] = 'application/javascript';
break;
case 'json':
$headers['content-type'] = 'application/json';
break;
}
if ( $headers['content-type'] ){
response.content_type = $headers['content-type'];
}
return $headers;
},
"stop": true
}
]
input: rules data
HTTP Requests (outbound):
default: on
on/off toggle
on:
intercept HTTP Requests and apply its corresponding set of rules
off:
disable this feature entirely
Path to Rules File
default: ''
refer to Comments / Implementation Notes for advanced usage
default:
0
(off)
useful while writing/testing new rules.
this feature will watch the rules file for changes, and reload its contents as needed.
HTTP Responses (inbound):
default: on
on/off toggle
on:
intercept HTTP Responses and apply its corresponding set of rules
off:
disable this feature entirely
Path to Rules File
default: ''
refer to Comments / Implementation Notes for advanced usage
default:
0
(off)
useful while writing/testing new rules.
this feature will watch the rules file for changes, and reload its contents as needed.
output: save()
HTTP Request Persistence:
default: on
on/off toggle
on:
the save()
helper function will save a record of the request to Output File
off:
disable this feature entirely
Path to Output File
default: ''
refer to Comments / Implementation Notes for advanced usage
default:
10
this feature is intended to prevent the Output File
from growing too large
> 0
:Output File
, the data is prepended. If after this addition there are more records stored in the file (ie: N
) than the specified maximum number of records (ie: X
), then only the first X
are retained… and the trailing (N-X)
are removed.0
:tools to replay saved requests
common settings:
default:
{DfltDwnld}
refer to Comments / Implementation Notes for advanced usage
wget:
wget
executable
default:
/usr/bin/wget
refer to Comments / Implementation Notes for advanced usage
wget
executable
default:
-c -nd --content-disposition --no-http-keep-alive --no-check-certificate -e robots=off --progress=dot:binary
curl:
a reference implementation that adds support for this tool exists in a separate branch: js/eval/replay/curl
this hasn't been merged into the
js/eval/master
branch due to a small incompatability, which is described pretty well across both:
extensions.Moz-Rewrite.debug
default:
false
boolean
true
:Browser Console
false
:extensions.Moz-Rewrite.case_sensitive
default:
false
boolean
true
:false
:Tools -> moz-rewrite -> user preferences
- same
Options
dialog as:Tools -> Add-ons
Extensions
moz-rewrite -> Options
- provides a graphical interface for the user to apply changes to the values of (non-hidden / user) addon preferences
Tools -> moz-rewrite -> view/replay saved requests
- saved HTTP Requests:
- list of all saved requests.
for each, a checkbox is followed by the corresponding URL.common form field controls
- replay selected requests using..
button that displays a list of all supported download tools.
this list currently contains:
- wget
- interactively identify each partial/incomplete download file
checkbox that
- when:
- one or more saved HTTP Requests are selected
- a download tool is chosen/activated from the list
- if
checked
:- for each of the selected saved HTTP Requests, an interactive
file picker
dialog will open and allow the user to choose the file path for the download.- this workflow allows using the external download tool to be used to save data to arbitrary paths within the filesystem,
rather than only to theDownload Directory
.- this is particularly useful for when the browser begins a download, but fails to complete.
in such a case,- if the request was saved…
or if the browser can re-request the download, and this subsequent request is saved…
without actually saving the file, and certainly NOT over writing the previously downloaded partial/incomplete file- then the interactive dialog would allow the user to browse for this partial/incomplete file download
- if not
checked
:- for each of the selected saved HTTP Requests, the chosen download tool will begin saving/resuming the requested data.
- this data will be saved to a file in the
Download Directory
- the filename will be determined by the external download tool.
factors that the tool may take into consideration:- a filename component of the requested URL
- a 'content-disposition' header of the response
command-line options for the tool (in addon preferences)
- fallback behavior when 'cancel' is chosen in interactive dialog
checkbox that
- when:
- interactively identify each partial/incomplete download file is
checked
- an interactive
file picker
dialog is closed by the user without having selected a filepathcancel
buttonclose window
(ie: "X") button
- if
checked
:- proceed with download and save to default directory
- if not
checked
:- skip replay of the specific saved request
data sets are stored in external files.
this allows them to be maintained using any text editor.
the addon asks to know the file path to each data set.
one for requests, one for responses.
there are two ways to specify a file path:
manually enter the path, which is parsed in such a way that portable/relative paths are supported.
when this path begins with one of the following special tokens,
the token will be replaced with the corresponding directory path.
the absolute path of these "special directories" may change from FF shutdown to startup,
but the relative path will remain valid.
these "special tokens/directories" include:
{ProfD}
:
profile directory
{CurProcD}
:
current working directory (usually the application's installation directory)
{ProfDefNoLoc}
: %installation%/defaults/profile
{PrfDef}
: %installation%/defaults/pref
{Desk}
:
user's desktop directory
{Home}
:
user's home directory
{DfltDwnld}
:
default Downloads directory
{TmpD}
:
operating system's temporary files directory
sample interpolation values:
Windows, PortableApps:
{ProfD}
: C:\PortableApps\Firefox\Data\profile
{CurProcD}
: C:\PortableApps\Firefox\App\firefox\browser
{ProfDefNoLoc}
: C:\PortableApps\Firefox\App\firefox\browser\defaults\profile
(note: directory does not exist)
{PrfDef}
: C:\PortableApps\Firefox\App\firefox\defaults\pref
{Desk}
: REG QUERY "HKCU\Software\Microsoft\Windows\CurrentVersion\Explorer\User Shell Folders" /v Desktop
{Home}
: %USERPROFILE%
{DfltDwnld}
: %USERPROFILE%\Downloads
{TmpD}
: %TEMP%
so.. if portability is a concern, then the following file/directory paths should work nicely:
(note: the specified paths must already exist; files/directories won't be created.)
{ProfD}/moz-rewrite/requests.js
{ProfD}/moz-rewrite/responses.js
{ProfD}/moz-rewrite/saved_requests.txt
{ProfD}/moz-rewrite/downloads
when enabled (in addon preferences), the addon will watch input data files for updates.
when the path to an input data file is changed (in addon preferences),
or an input data file having a watched path has been updated (identified by its last modification date):
when a request/response observer is notified:
the heavy lifting is converting the javascript entered by the user in the rules files into (in-memory) data objects.
eval()
functioneval()
function.js/Cu.evalInSandbox/master
(default, current):
Cu.Sandbox
and Cu.evalInSandbox
APIsJSON.parse()
function
json/master
branch is available on AMOjs/Cu.evalInSandbox/master
branch is pending review on AMOGPLv2 Copyright (c) 2014, Warren Bank