# railgun.scope

The scope module contains a useful Scope class which can contain any number of rules that
can further be used to determine if a request meets some user-defined conditions. The module
is largely used to build a Scope object that will be used to filter requests received by a
proxy server or processed by a spider.

Example:

```js
const railgun = require('railgun')

let scope = new railgun.scope.Scope()
// Create a new rule for the scope with the label "matchesHost" that tests whether the
// hostname/domain of the site is "vulnsite.ninja".
scope.addRule('matchesHost', railgun.scope.rules.matchHost(/vulnsite.ninja/))

let builder = new railgun.Request('GET', 'http://vulnsite.ninja/index.html')
let spider = new railgun.Spider({}, builder)

// Create a middleware function (usable by both the spider and a proxy server) that
// will reject requests that do not satisfy all of the scope rules.
spider.onRequest(scope.filter())
spider.subscribe({onRequest: function (req) {
  console.log('Making a request for', req.url)
})
spider.crawl()
```

## Methods

### railgun.scope.Scope#constructor

The Scope constructor takes no arguments and returns a new Scope object.

### railgun.scope.Scope#addRule

scope.Scope#addrule accepts two arguments:

1. A label string for the rule
2. A rule function

A rule function has the form

```js
function (requestBuilder) {
  return // true if the request follows the rule or else false
}
```

### railgun.scope.Scope#removeRule

scope.Scope#removeRule removes a previously registered rule.  Its argument is a label string
for a rule registered to the scope, which it uses to find and remove that rule.

### railgun.scope.Scope#covers

scope.Scope#covers determines whether a request (builder), its only argument, satisfies all of
the registered rules.  Users should not expect rules to be applied in any particular order.

### railgun.scope.Scope#filter

scope.Scope#filter accepts no arguments and returns a middleware function that will test requests
being processed to see if the scope covers the request. In the case that the request does not fit
within the scope, the scope object will call the request's `reject` method. Request builders have
a `reject` method attached to them by the proxy server and by the spider which handle stopping
the processing of the request.

## Module functions

### railgun.scope.rules.matchHost

railgun.scope.rules.matchHost accepts a regular expression and returns a rule function that will
test an incoming request's host/domain against the provided regular expression.

### railgun.scope.rules.matchPort

railgun.scope.rules.matchPort accepts a regular expression and returns a rule function that will
test an incoming request's port number against the provided regular expression.

### railgun.scope.rules.matchMethod

railgun.scope.rules.matchMethod accepts a regular expression and returns a rule function that will
test an incoming request's method against the provided regular expression.

### railgun.scope.rules.matchHeader

railgun.scope.rules.matchHost accepts a header name and a regular expression and 
returns a rule function that will test if an incoming request has the provided header and if that
header's value matches the provided regular expression.