An dive into our proto under the hood
Config
is its list of Rule
s.
Each rule is composed of two parts: a “matching spec” and an “action spec”. The matching spec says whether a rule applies, the “action spec” says what it does.
Here’s an example configuration:
BLOCK_MODE_BLOCK
) to google.com and its subdomains (*.google.com
).
google.com
, but only for user/group with ID 1234
.
If a rule’s matching spec is empty, it always applies. Example:
google.com
and its subdomains, but it allows access to images.google.com
.
Rules can also have nested rules, which override their parent if they match. Nested rules are only applied if their parent rule also matched.
Example:
*.amazon.com
, and normally blocks access to *.google.com
. However, access to *.google.com
is permitted for user/group 1234
. That user/group is still not allowed to access *.amazon.com
.
Action specs only override the fields they specify; any unspecified fields are inherited.
Example:
BLOCK_MODE_WARN
) for google.com
and its subdomains, and users need to re-accept the warning every hour (warn_dismiss_duration
). The second rule overrides the warn_dismiss_duration
and says what warning page to show for maps.google.com
(warn_template
), but it still inherits the block_mode
value from the previous rule.
Rule
can contain any number of CookieRule
s. These specify things like whether a cookie should be encrypted, blocked, or allowed through. Just like regular Rule
s, each CookieRule
has its own matching spec and action spec. All the same inheritance, matching, and override rules apply to CookieRule
s as they do to regular Rule
s. Note that since CookieRule
s are nested inside of Rule
s, they only apply if their parent Rule
applies.
Example:
Rule
has no matching spec, so this applies to all domains. The inner CookieRule
says that cookies should be encrypted (transform: true
) if they are HttpOnly cookies.
config.proto
file itself.
inja
library.
At the most basic, templates can just be regular HTML. Example:
block_template: "pirate"
in the Rule
s.
inja
, templates include or extend other templates.
Consider the following template:
styles
defined. The contents of the styles
template will be included in this template, replacing the {% ... %}
directive.
A template can also extend another template, replacing specific fields.
%{ include %}
d or extended. They are:
__default__
: The default template, used if the config doesn’t specify a warn_template
or block_template
.__default_styles__
: Some default styles. Used in the default template.__continue__
: The “Continue” button for warning pages, which dismisses the warning and allows the user to proceed.__missing__
: Fallback, used if the config tries to include or extend a template that doesn’t exist.__error__
: Fallback, used if there’s some other error in the template syntax.{% include "__continue__" %}
somewhere. If not, users will be unable to continue past the warning.
__error__
template, displayed to users if there’s an error in rendering the user-supplied template:
__default__
template. It overrides a block in the default template called error
. The other blocks, like warning_title
, are not overridden.
If a block is not explicitly mentioned when extending a template, that block will be empty. To avoid this, call super()
like this:
__default__
template contains the following overrideable blocks:
blocked_title
: The title to display if a page is blocked.blocked_messaage
: The message to display if a page is blocked.warning_title
The title to display if a page should show a warning.warning_message
: The message to display if a page should show a warning.error
: A block for displaying an error.{{ var_name }}
in the template. The variables provided are defined in config.proto
’s message TemplateFields
.
Rule
s can match against whole categories of domains. A collection of default categories is provided, and custom categories can be created. See the Categories page for more information.
Each custom category contains a list of domains - literal or wildcard. If a custom category has the same name as a previous category, it overrides it. This works for overriding the built-in categories too.