From 01834fe901117809490fbf59b104833bdd88ea20 Mon Sep 17 00:00:00 2001 From: Wojtek Kosior Date: Wed, 26 Oct 2022 14:30:28 +0200 Subject: [proxy] add documentation page describing URL patterns in Haketilo --- src/hydrilla/locales/en_US/LC_MESSAGES/messages.po | 335 +++++++++++++++++++-- 1 file changed, 312 insertions(+), 23 deletions(-) (limited to 'src/hydrilla/locales') diff --git a/src/hydrilla/locales/en_US/LC_MESSAGES/messages.po b/src/hydrilla/locales/en_US/LC_MESSAGES/messages.po index 43e6d18..35e4646 100644 --- a/src/hydrilla/locales/en_US/LC_MESSAGES/messages.po +++ b/src/hydrilla/locales/en_US/LC_MESSAGES/messages.po @@ -1,13 +1,20 @@ -# SPDX-License-Identifier: CC0-1.0 +# SPDX-License-Identifier: GPL-3.0-or-later OR CC-BY-SA-4.0 +# English translations for Hydrilla&Haketilo. # -# English (United States) translations for hydrilla. -# Copyright (C) 2021, 2022 Wojtek Kosior -# Available under the terms of Creative Commons Zero v1.0 Universal. +# This file is part of Hydrilla&Haketilo. +# Copyright (C) 2021-2022 Wojtek Kosior +# Dual licensed under +# * GNU General Public License v3.0 or later and +# * Creative Commons Attribution Share Alike 4.0 International. +# You can choose to use either of these licenses or both. +# I, Wojtek Kosior, thereby promise not to sue for violation of this +# file's licenses. Although I request that you do not make use of this +# code in a proprietary work, I am not going to enforce this in court. msgid "" msgstr "" "Project-Id-Version: hydrilla 2.0\n" "Report-Msgid-Bugs-To: koszko@koszko.org\n" -"POT-Creation-Date: 2022-10-25 10:28+0200\n" +"POT-Creation-Date: 2022-10-26 14:26+0200\n" "PO-Revision-Date: 2022-02-12 00:00+0000\n" "Last-Translator: Wojtek Kosior \n" "Language: en_US\n" @@ -213,39 +220,39 @@ msgstr "" "\n" "{}" -#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:25 +#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:34 msgid "info.base.title" msgstr "Page info" -#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:30 +#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:39 msgid "info.base.heading.page_info" msgstr "Haketilo page handling details" -#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:33 +#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:42 msgid "info.base.page_url_label" msgstr "Page URL" -#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:41 +#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:50 msgid "info.base.page_policy_label" msgstr "Active policy" -#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:53 +#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:62 msgid "info.base.more_config_options_label" msgstr "Configure" -#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:61 +#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:70 msgid "info.base.this_site_script_blocking_button" msgstr "JS blocking on this site" -#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:64 +#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:73 msgid "info.base.this_site_payload_button" msgstr "Payload for this site" -#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:67 +#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:76 msgid "info.base.this_page_script_blocking_button" msgstr "JS blocking on this page" -#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:70 +#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:79 msgid "info.base.this_page_payload_button" msgstr "Payload for this page" @@ -312,6 +319,288 @@ msgstr "Requested file could not be found." msgid "api.resource_not_enabled_for_access" msgstr "Requested resource is not enabled for access." +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:30 +msgid "doc.url_patterns.html.intro" +msgstr "" +"We want to be able to apply different rules and custom scripts for " +"different websites. However, merely specifying \"do this for all " +"documents under https://example.com\" is not enough. Single " +"site's pages might differ strongly and require different custom scripts " +"to be loaded. Always matching against a full URL like " +"https://example.com/something/somethingelse is also not a " +"good option. It doesn't allow us to properly handle a site that serves " +"similar pages for multiple values substituted for " +"somethingelse." + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:35 +msgid "doc.url_patterns.heading.employed_solution" +msgstr "Employed solution" + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:38 +msgid "doc.url_patterns.html.wildcards_intro" +msgstr "" +"Wildcards are being used to address the problem. Each payload and rule in" +" Haketilo has a URL pattern that specifies to which internet pages it " +"applies. A URL pattern can be as as simple as literal URL in which case " +"it only matches itself. It can also contain wildcards in the form of one " +"or more asterisks (*) that correspond to multiple possible " +"strings occurring in that place." + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:42 +msgid "doc.url_patterns.html.wildcards_types_introduced" +msgstr "" +"Wildcards can appear in URL's domain and path that follows it. These 2 " +"types of wildcards are handled separately." + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:47 +msgid "doc.url_patterns.label.domain_wildcards" +msgstr "Domain wildcards" + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:50 +msgid "doc.url_patterns.html.domain_wildcards_intro" +msgstr "" +"A domain wildcard takes the form of one, two or three asterisks occurring" +" in place of a single domain name segment at the beginning (left). " +"Depending on the number of asterisks, the meaning is as follows" + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:55 +msgid "doc.url_patterns.html.domain_no_asterisks_example" +msgstr "" +"no asterisks (e.g. example.com) - match domain name exactly " +"(e.g. example.com)" + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:58 +msgid "doc.url_patterns.html.domain_one_asterisk_example" +msgstr "" +"one asterisk (e.g. *.example.com) - match all domains " +"resulting from substituting * with a single segment (e.g. " +"banana.example.com or pineapple.example.com but" +" not pineapple.pen.example.com " +"nor example.com)" + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:61 +msgid "doc.url_patterns.html.domain_two_asterisks_example" +msgstr "" +"two asterisks (e.g. **.example.com) - match all domains " +"resulting from substituting ** with two" +" or more segments (e.g. monad.breakfast.example.com " +"or pure.monad.breakfast.example.com but not cabalhell.example.com nor " +"example.com)" + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:64 +msgid "doc.url_patterns.html.domain_three_asterisks_example" +msgstr "" +"three asterisks (e.g. ***.example.com) - match all domains " +"resulting from substituting *** with zero or more segments (e.g. " +"hello.parkmeter.example.com or " +"iliketrains.example.com or example.com)" + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:70 +msgid "doc.url_patterns.label.path_wildcards" +msgstr "Path wildcards" + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:73 +msgid "doc.url_patterns.html.path_wildcards_intro" +msgstr "" +"A path wildcard takes the form of one, two or three asterisks occurring " +"in place of a single path segment at the end of path (right). Depending " +"on the number of asterisks, the meaning is as follows" + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:78 +msgid "doc.url_patterns.html.path_no_asterisks_example" +msgstr "" +"no asterisks (e.g. /joke/clowns) - match path exactly (e.g. " +"/joke/clowns)" + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:81 +msgid "doc.url_patterns.html.path_one_asterisk_example" +msgstr "" +"one asterisk (e.g. /itscalled/*) - match all paths resulting" +" from substituting * with a single segment (e.g. " +"/itscalled/gnulinux or /itscalled/glamp but " +"not /itscalled/ nor " +"/itscalled/gnu/linux)" + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:84 +msgid "doc.url_patterns.html.path_two_asterisks_example" +msgstr "" +"two asterisks (e.g. /another/**) - match all paths resulting" +" from substituting ** with two or " +"more segments (e.g. /another/nsa/backdoor or " +"/another/best/programming/language but not /another/apibreak nor " +"/another)" + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:87 +msgid "doc.url_patterns.html.path_three_asterisks_example" +msgstr "" +"three asterisks (e.g. /mail/dmarc/***) - match all paths " +"resulting from substituting *** with zero or more segments (e.g. " +"/mail/dmarc/spf, /mail/dmarc or " +"/mail/dmarc/dkim/failure but not" +" /mail/)" + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:92 +msgid "doc.url_patterns.html.path_trailing_slash" +msgstr "" +"If pattern ends without a trailing slash, it " +"mathes paths with any number of trailing slashes, including zero. If " +"pattern ends with a trailing slash, it only " +"mathes paths with one or more trailing slashes. For example, " +"/itscalled/* matches /itscalled/gnulinux, " +"/itscalled/gnulinux/ and /itscalled/gnulinux// " +"while /itscalled/*/ only matches " +"/itscalled/gnulinux/ and /itscalled/gnulinux// " +"out of those three." + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:96 +msgid "doc.url_patterns.html.path_trailing_slash_priority" +msgstr "" +"If two patterns only differ by the presence of a trailing slash, pattern " +"with a trailing slash is considered more specific." + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:100 +msgid "doc.url_patterns.html.path_literal_trailing_asterisks" +msgstr "" +"Additionally, any path with literal trailing asterisks is matched by " +"itself, even if such pattern would otherwise be treated as wildcard (e.g." +" /gobacktoxul/** matches /gobacktoxul/**). This" +" is likely to change in the future and would best not be relied upon. " +"Appending three additional asterisks to path pattern to represent literal" +" asterisks is being considered." + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:105 +msgid "doc.url_patterns.label.protocol_wildcards" +msgstr "URL scheme wildcard" + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:108 +msgid "doc.url_patterns.html.protocol_wildcards" +msgstr "" +"http:// and https:// shemes in the URL are " +"matched exactly. However, starting with Haketilo 3.0, it is also possible" +" for scheme pseudo-wildcard of http*:// to be used. Use of " +"URL pattern with this scheme is equivalent to the use of 2 separate " +"patterns starting with http:// and https://, " +"respectively. For example, pattern http*://example.com shall" +" match both https://example.com and " +"http://example.com." + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:112 +msgid "doc.url_patterns.html.protocol_wildcards_are_aliases" +msgstr "" +"http*:// may be considered not to be a true wildcard but " +"rather an alias for either of the other 2 values. As of Haketilo 3.0, the" +" speicificity of a URL pattern starting with http*:// is " +"considered to be the same as that of the corresponding URL pattern " +"starting with http:// or https://. In case of a" +" conflict, the order of precedence of such patterns is unspecified. This " +"behavior is likely to change in the future versions of Haketilo." + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:117 +msgid "doc.url_patterns.label.wildcard_priorities" +msgstr "Wildcard pattern priorities and querying" + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:120 +msgid "doc.url_patterns.priorities_intro" +msgstr "" +"In case multiple patterns match some URL, the more specific one is " +"preferred. Specificity is considered as follows" + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:125 +msgid "doc.url_patterns.priorities_rule_path_ending" +msgstr "" +"If patterns only differ in the final path segment, the one with least " +"wildcard asterisks in that segment if preferred." + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:128 +msgid "doc.url_patterns.priorities_rule_path_length" +msgstr "" +"If patterns, besides the above, only differ in path length, one with " +"longer path is preferred. Neither final wildcard segment nor trailing " +"dashes account for path length." + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:131 +msgid "doc.url_patterns.priorities_rule_domain_beginning" +msgstr "" +"If patterns, besides the above, only differ in the initial domain " +"segment, one with least wildcard asterisks in that segment is preferred." + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:134 +#, fuzzy +msgid "doc.url_patterns.priorities_rule_domain_length" +msgstr "" +"If patterns differ in domain length, one with longer domain is preferred." +" Initial wildcard segment does not account for domain length." + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:139 +msgid "doc.url_patterns.html.priorities_example1_intro" +msgstr "" +"As an example, consider the URL " +"http://settings.query.example.com/google/tries/destroy/adblockers//." +" Patterns matching it are, in the following order" + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:266 +msgid "doc.url_patterns.html.priorities_example1_note" +msgstr "" +"Variants of those patterns starting with http*:// would of " +"course match as well. They have been omitted for simplicity." + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:270 +msgid "doc.url_patterns.html.priorities_example2_intro" +msgstr "" +"For a simpler URL like https://example.com the patterns " +"would be" + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:281 +msgid "doc.url_patterns.html.priorities_example2_note" +msgstr "" +"Variants of those patterns with a trailing dash added would not match the URL. Also, the pattern variants " +"starting with http*:// have been once again omitted." + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:286 +msgid "doc.url_patterns.label.limits" +msgstr "Limits" + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:289 +msgid "doc.url_patterns.limits" +msgstr "" +"In order to prevent some easy-to-conduct DoS attacks, older versions of " +"Haketilo and Hydrilla limited the lengths of domain and path parts of " +"processed URLs. This is no longer the case." + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:294 +msgid "doc.url_patterns.heading.alt_solution" +msgstr "Alternative solution idea: mimicking web server mechanics" + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:297 +msgid "doc.url_patterns.url_pattern_drawbacks" +msgstr "" +"While wildcard patterns as presented give a lot of flexibility, they are " +"not the only viable approach to specifying what URLs to apply " +"rules/payloads to. In fact, wildcards are different from how the server " +"side of a typical website decides what to return for a given URL request." + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:301 +msgid "doc.url_patterns.server_behavior_mimicking_idea" +msgstr "" +"In a typical scenario, an HTTP server like Apache reads configuration " +"files provided by its administrator and uses various (virtual host, " +"redirect, request rewrite, CGI, etc.) instructions to decide how to " +"handle given URL. Perhps using a scheme that mimics the configuration " +"options typically used with web servers would give more efficiency in " +"specifying what page settings to apply when." + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:305 +msgid "doc.url_patterns.approach_may_be_considered" +msgstr "This approach may be considered in the future." + #: src/hydrilla/proxy/state_impl/concrete_state.py:111 msgid "err.proxy.unknown_db_schema" msgstr "" @@ -1449,39 +1738,39 @@ msgstr "" "HTTP server like Apache2 or Nginx. You can configure Hydrilla through the" " /etc/hydrilla/config.json file." -#: src/hydrilla/url_patterns.py:139 +#: src/hydrilla/url_patterns.py:127 msgid "err.url_pattern_{}.bad" msgstr "Not a valid Haketilo URL pattern: {}" -#: src/hydrilla/url_patterns.py:142 +#: src/hydrilla/url_patterns.py:130 msgid "err.url_{}.bad" msgstr "Not a valid URL: {}" -#: src/hydrilla/url_patterns.py:149 +#: src/hydrilla/url_patterns.py:137 msgid "err.url_pattern_{}.bad_scheme" msgstr "URL pattern has an unknown scheme: {}" -#: src/hydrilla/url_patterns.py:152 +#: src/hydrilla/url_patterns.py:140 msgid "err.url_{}.bad_scheme" msgstr "URL has an unknown scheme: {}" -#: src/hydrilla/url_patterns.py:157 +#: src/hydrilla/url_patterns.py:145 msgid "err.url_pattern_{}.special_scheme_port" msgstr "URL pattern has an explicit port while it shouldn't: {}" -#: src/hydrilla/url_patterns.py:169 +#: src/hydrilla/url_patterns.py:157 msgid "err.url_pattern_{}.bad_port" msgstr "URL pattern has a port outside of allowed range (1-65535): {}" -#: src/hydrilla/url_patterns.py:172 +#: src/hydrilla/url_patterns.py:160 msgid "err.url_{}.bad_port" msgstr "URL has a port outside of allowed range (1-65535): {}" -#: src/hydrilla/url_patterns.py:193 +#: src/hydrilla/url_patterns.py:181 msgid "err.url_pattern_{}.has_query" msgstr "URL pattern has a query string while it shouldn't: {}" -#: src/hydrilla/url_patterns.py:197 +#: src/hydrilla/url_patterns.py:185 msgid "err.url_pattern_{}.has_frag" msgstr "URL pattern has a fragment string while it shouldn't: {}" -- cgit v1.2.3