From 01834fe901117809490fbf59b104833bdd88ea20 Mon Sep 17 00:00:00 2001
From: Wojtek Kosior <koszko@koszko.org>
Date: Wed, 26 Oct 2022 14:30:28 +0200
Subject: [proxy] add documentation page describing URL patterns in Haketilo

---
 .../js_error_blocked_info.html.jinja               |   2 +-
 src/hydrilla/proxy/self_doc.py                     |  11 +
 src/hydrilla/proxy/self_doc/doc_base.html.jinja    |  65 +++++
 .../proxy/self_doc/url_patterns.html.jinja         | 308 +++++++++++++++++++++
 src/hydrilla/proxy/web_ui/root.py                  |  18 +-
 5 files changed, 400 insertions(+), 4 deletions(-)
 create mode 100644 src/hydrilla/proxy/self_doc.py
 create mode 100644 src/hydrilla/proxy/self_doc/doc_base.html.jinja
 create mode 100644 src/hydrilla/proxy/self_doc/url_patterns.html.jinja

(limited to 'src/hydrilla/proxy')

diff --git a/src/hydrilla/proxy/policies/info_pages_templates/js_error_blocked_info.html.jinja b/src/hydrilla/proxy/policies/info_pages_templates/js_error_blocked_info.html.jinja
index c76d42b..181b219 100644
--- a/src/hydrilla/proxy/policies/info_pages_templates/js_error_blocked_info.html.jinja
+++ b/src/hydrilla/proxy/policies/info_pages_templates/js_error_blocked_info.html.jinja
@@ -17,6 +17,6 @@ Copyright (C) 2022 Wojtek Kosior <koszko@koszko.org>
   {% if settings.advanced_user %}
     {{ label(_('info.js_error_blocked.stacktrace')) }}
 
-    {{ verbatim(traceback) }}
+    {% call verbatim() %}{{ traceback }}{% endcall %}
   {% endif %}
 {% endblock %}
diff --git a/src/hydrilla/proxy/self_doc.py b/src/hydrilla/proxy/self_doc.py
new file mode 100644
index 0000000..a1a2485
--- /dev/null
+++ b/src/hydrilla/proxy/self_doc.py
@@ -0,0 +1,11 @@
+# SPDX-License-Identifier: CC0-1.0
+
+# Copyright (C) 2022 Wojtek Kosior <koszko@koszko.org>
+#
+# Available under the terms of Creative Commons Zero v1.0 Universal.
+
+import jinja2
+
+loader = jinja2.PackageLoader(__package__, package_path='self_doc')
+
+page_names = {'url_patterns'}
diff --git a/src/hydrilla/proxy/self_doc/doc_base.html.jinja b/src/hydrilla/proxy/self_doc/doc_base.html.jinja
new file mode 100644
index 0000000..cef1abb
--- /dev/null
+++ b/src/hydrilla/proxy/self_doc/doc_base.html.jinja
@@ -0,0 +1,65 @@
+{#
+SPDX-License-Identifier: GPL-3.0-or-later OR CC-BY-SA-4.0
+
+Base template for documentation pages when outputting HTML.
+
+This file is part of Hydrilla&Haketilo.
+
+Copyright (C) 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.
+#}
+{% if doc_output == 'html_hkt_mitm_it' %}
+  {% set doc_base_filename = 'hkt_mitm_it_base.html.jinja' %}
+{% else %}
+  {% set doc_base_filename = 'base.html.jinja' %}
+{% endif %}
+{% extends doc_base_filename %}
+
+{% set sections = namespace(count=0) %}
+
+{% macro section() %}
+  {% if sections.count > 0 %}
+    <div class="horizontal-separator"></div>
+  {% endif %}
+  {% set sections.count = sections.count + 1 %}
+
+  {{ caller()|safe }}
+{% endmacro %}
+
+{% macro link(where, text) -%}
+  <a href="{{ where }}">{{ text }}</a>
+{%- endmacro %}
+
+{% macro paragraph() %}
+  <p class="has-colored-links">
+    {{ caller()|safe }}
+  </p>
+{% endmacro %}
+
+{% macro big_heading(text) %}
+  <h3>
+    {{ text }}
+  </h3>
+{% endmacro %}
+
+{% macro medium_heading(text) %}
+  <h4>
+    {{ text }}
+  </h4>
+{% endmacro %}
+
+{% macro small_heading(text) %}
+  <label class="section-label">
+    {{ text }}
+  </label>
+{% endmacro %}
diff --git a/src/hydrilla/proxy/self_doc/url_patterns.html.jinja b/src/hydrilla/proxy/self_doc/url_patterns.html.jinja
new file mode 100644
index 0000000..45a0db3
--- /dev/null
+++ b/src/hydrilla/proxy/self_doc/url_patterns.html.jinja
@@ -0,0 +1,308 @@
+{#
+SPDX-License-Identifier: GPL-3.0-or-later OR CC-BY-SA-4.0
+
+Documentation page describing URL patterns understood by Haketilo.
+
+This file is part of Hydrilla&Haketilo.
+
+Copyright (C) 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.
+#}
+{% extends "doc_base.html.jinja" %}
+
+{% block title %}URL patterns{% endblock %}
+
+{% block main %}
+  {{ big_heading('URL patterns') }}
+
+  {% call section() %}
+    {% call paragraph() %}
+      {{ _('doc.url_patterns.html.intro')|safe }}
+    {% endcall %}
+  {% endcall %}
+
+  {% call section() %}
+    {{ medium_heading(_('doc.url_patterns.heading.employed_solution')) }}
+
+    {% call paragraph() %}
+      {{ _('doc.url_patterns.html.wildcards_intro')|safe }}
+    {% endcall %}
+
+    {% call paragraph() %}
+      {{ _('doc.url_patterns.html.wildcards_types_introduced')|safe }}
+    {% endcall %}
+  {% endcall %}
+
+  {% call section() %}
+    {{ small_heading(_('doc.url_patterns.label.domain_wildcards')) }}
+
+    {% call paragraph() %}
+      {{ _('doc.url_patterns.html.domain_wildcards_intro')|safe }}
+    {% endcall %}
+
+    {% call unordered_list() %}
+      {% call list_entry() %}
+        {{ _('doc.url_patterns.html.domain_no_asterisks_example')|safe }}
+      {% endcall %}
+      {% call list_entry() %}
+        {{ _('doc.url_patterns.html.domain_one_asterisk_example')|safe }}
+      {% endcall %}
+      {% call list_entry() %}
+        {{ _('doc.url_patterns.html.domain_two_asterisks_example')|safe }}
+      {% endcall %}
+      {% call list_entry() %}
+        {{ _('doc.url_patterns.html.domain_three_asterisks_example')|safe }}
+      {% endcall %}
+    {% endcall %}
+  {% endcall %}
+
+  {% call section() %}
+    {{ small_heading(_('doc.url_patterns.label.path_wildcards')) }}
+
+    {% call paragraph() %}
+      {{ _('doc.url_patterns.html.path_wildcards_intro')|safe }}
+    {% endcall %}
+
+    {% call unordered_list() %}
+      {% call list_entry() %}
+        {{ _('doc.url_patterns.html.path_no_asterisks_example')|safe }}
+      {% endcall %}
+      {% call list_entry() %}
+        {{ _('doc.url_patterns.html.path_one_asterisk_example')|safe }}
+      {% endcall %}
+      {% call list_entry() %}
+        {{ _('doc.url_patterns.html.path_two_asterisks_example')|safe }}
+      {% endcall %}
+      {% call list_entry() %}
+        {{ _('doc.url_patterns.html.path_three_asterisks_example')|safe }}
+      {% endcall %}
+    {% endcall %}
+
+    {% call paragraph() %}
+      {{ _('doc.url_patterns.html.path_trailing_slash')|safe }}
+    {% endcall %}
+
+    {% call paragraph() %}
+      {{ _('doc.url_patterns.html.path_trailing_slash_priority')|safe }}
+    {% endcall %}
+
+    {% call paragraph() %}
+      {{ _('doc.url_patterns.html.path_literal_trailing_asterisks')|safe }}
+    {% endcall %}
+  {% endcall %}
+
+  {% call section() %}
+    {{ small_heading(_('doc.url_patterns.label.protocol_wildcards')) }}
+
+    {% call paragraph() %}
+      {{ _('doc.url_patterns.html.protocol_wildcards')|safe }}
+    {% endcall %}
+
+    {% call paragraph() %}
+      {{ _('doc.url_patterns.html.protocol_wildcards_are_aliases')|safe }}
+    {% endcall %}
+  {% endcall %}
+
+  {% call section() %}
+    {{ small_heading(_('doc.url_patterns.label.wildcard_priorities')) }}
+
+    {% call paragraph() %}
+      {{ _('doc.url_patterns.priorities_intro') }}
+    {% endcall %}
+
+    {% call unordered_list() %}
+      {% call list_entry() %}
+        {{ _('doc.url_patterns.priorities_rule_path_ending')|safe }}
+      {% endcall %}
+      {% call list_entry() %}
+        {{ _('doc.url_patterns.priorities_rule_path_length')|safe }}
+      {% endcall %}
+      {% call list_entry() %}
+        {{ _('doc.url_patterns.priorities_rule_domain_beginning')|safe }}
+      {% endcall %}
+      {% call list_entry() %}
+        {{ _('doc.url_patterns.priorities_rule_domain_length')|safe }}
+      {% endcall %}
+    {% endcall %}
+
+    {% call paragraph() %}
+      {{ _('doc.url_patterns.html.priorities_example1_intro')|safe }}
+    {% endcall %}
+
+    {% call verbatim() %}
+http://settings.query.example.com/google/tries/destroy/adblockers/
+http://settings.query.example.com/google/tries/destroy/adblockers
+http://settings.query.example.com/google/tries/destroy/adblockers/***/
+http://settings.query.example.com/google/tries/destroy/adblockers/***
+http://settings.query.example.com/google/tries/destroy/*/
+http://settings.query.example.com/google/tries/destroy/*
+http://settings.query.example.com/google/tries/destroy/***/
+http://settings.query.example.com/google/tries/destroy/***
+http://settings.query.example.com/google/tries/**/
+http://settings.query.example.com/google/tries/**
+http://settings.query.example.com/google/tries/***/
+http://settings.query.example.com/google/tries/***
+http://settings.query.example.com/google/**/
+http://settings.query.example.com/google/**
+http://settings.query.example.com/google/***/
+http://settings.query.example.com/google/***
+http://settings.query.example.com/**/
+http://settings.query.example.com/**
+http://settings.query.example.com/***/
+http://settings.query.example.com/***
+http://***.settings.query.example.com/google/tries/destroy/adblockers/
+http://***.settings.query.example.com/google/tries/destroy/adblockers
+http://***.settings.query.example.com/google/tries/destroy/adblockers/***/
+http://***.settings.query.example.com/google/tries/destroy/adblockers/***
+http://***.settings.query.example.com/google/tries/destroy/*/
+http://***.settings.query.example.com/google/tries/destroy/*
+http://***.settings.query.example.com/google/tries/destroy/***/
+http://***.settings.query.example.com/google/tries/destroy/***
+http://***.settings.query.example.com/google/tries/**/
+http://***.settings.query.example.com/google/tries/**
+http://***.settings.query.example.com/google/tries/***/
+http://***.settings.query.example.com/google/tries/***
+http://***.settings.query.example.com/google/**/
+http://***.settings.query.example.com/google/**
+http://***.settings.query.example.com/google/***/
+http://***.settings.query.example.com/google/***
+http://***.settings.query.example.com/**/
+http://***.settings.query.example.com/**
+http://***.settings.query.example.com/***/
+http://***.settings.query.example.com/***
+http://*.query.example.com/google/tries/destroy/adblockers/
+http://*.query.example.com/google/tries/destroy/adblockers
+http://*.query.example.com/google/tries/destroy/adblockers/***/
+http://*.query.example.com/google/tries/destroy/adblockers/***
+http://*.query.example.com/google/tries/destroy/*/
+http://*.query.example.com/google/tries/destroy/*
+http://*.query.example.com/google/tries/destroy/***/
+http://*.query.example.com/google/tries/destroy/***
+http://*.query.example.com/google/tries/**/
+http://*.query.example.com/google/tries/**
+http://*.query.example.com/google/tries/***/
+http://*.query.example.com/google/tries/***
+http://*.query.example.com/google/**/
+http://*.query.example.com/google/**
+http://*.query.example.com/google/***/
+http://*.query.example.com/google/***
+http://*.query.example.com/**/
+http://*.query.example.com/**
+http://*.query.example.com/***/
+http://*.query.example.com/***
+http://***.query.example.com/google/tries/destroy/adblockers/
+http://***.query.example.com/google/tries/destroy/adblockers
+http://***.query.example.com/google/tries/destroy/adblockers/***/
+http://***.query.example.com/google/tries/destroy/adblockers/***
+http://***.query.example.com/google/tries/destroy/*/
+http://***.query.example.com/google/tries/destroy/*
+http://***.query.example.com/google/tries/destroy/***/
+http://***.query.example.com/google/tries/destroy/***
+http://***.query.example.com/google/tries/**/
+http://***.query.example.com/google/tries/**
+http://***.query.example.com/google/tries/***/
+http://***.query.example.com/google/tries/***
+http://***.query.example.com/google/**/
+http://***.query.example.com/google/**
+http://***.query.example.com/google/***/
+http://***.query.example.com/google/***
+http://***.query.example.com/**/
+http://***.query.example.com/**
+http://***.query.example.com/***/
+http://***.query.example.com/***
+http://**.example.com/google/tries/destroy/adblockers/
+http://**.example.com/google/tries/destroy/adblockers
+http://**.example.com/google/tries/destroy/adblockers/***/
+http://**.example.com/google/tries/destroy/adblockers/***
+http://**.example.com/google/tries/destroy/*/
+http://**.example.com/google/tries/destroy/*
+http://**.example.com/google/tries/destroy/***/
+http://**.example.com/google/tries/destroy/***
+http://**.example.com/google/tries/**/
+http://**.example.com/google/tries/**
+http://**.example.com/google/tries/***/
+http://**.example.com/google/tries/***
+http://**.example.com/google/**/
+http://**.example.com/google/**
+http://**.example.com/google/***/
+http://**.example.com/google/***
+http://**.example.com/**/
+http://**.example.com/**
+http://**.example.com/***/
+http://**.example.com/***
+http://***.example.com/google/tries/destroy/adblockers/
+http://***.example.com/google/tries/destroy/adblockers
+http://***.example.com/google/tries/destroy/adblockers/***/
+http://***.example.com/google/tries/destroy/adblockers/***
+http://***.example.com/google/tries/destroy/*/
+http://***.example.com/google/tries/destroy/*
+http://***.example.com/google/tries/destroy/***/
+http://***.example.com/google/tries/destroy/***
+http://***.example.com/google/tries/**/
+http://***.example.com/google/tries/**
+http://***.example.com/google/tries/***/
+http://***.example.com/google/tries/***
+http://***.example.com/google/**/
+http://***.example.com/google/**
+http://***.example.com/google/***/
+http://***.example.com/google/***
+http://***.example.com/**/
+http://***.example.com/**
+http://***.example.com/***/
+http://***.example.com/***
+    {% endcall %}
+
+    {% call paragraph() %}
+      {{ _('doc.url_patterns.html.priorities_example1_note')|safe }}
+    {% endcall %}
+
+    {% call paragraph() %}
+      {{ _('doc.url_patterns.html.priorities_example2_intro')|safe }}
+    {% endcall %}
+
+    {% call verbatim() %}
+https://example.com
+https://example.com/***
+https://***.example.com
+https://***.example.com/***
+    {% endcall %}
+
+    {% call paragraph() %}
+      {{ _('doc.url_patterns.html.priorities_example2_note')|safe }}
+    {% endcall %}
+  {% endcall %}
+
+  {% call section() %}
+    {{ small_heading(_('doc.url_patterns.label.limits')) }}
+
+    {% call paragraph() %}
+      {{ _('doc.url_patterns.limits')|safe }}
+    {% endcall %}
+  {% endcall %}
+
+  {% call section() %}
+    {{ medium_heading(_('doc.url_patterns.heading.alt_solution')) }}
+
+    {% call paragraph() %}
+      {{ _('doc.url_patterns.url_pattern_drawbacks') }}
+    {% endcall %}
+
+    {% call paragraph() %}
+      {{ _('doc.url_patterns.server_behavior_mimicking_idea') }}
+    {% endcall %}
+
+    {% call paragraph() %}
+      {{ _('doc.url_patterns.approach_may_be_considered') }}
+    {% endcall %}
+  {% endcall %}
+{% endblock main %}
diff --git a/src/hydrilla/proxy/web_ui/root.py b/src/hydrilla/proxy/web_ui/root.py
index 4430bb6..917c063 100644
--- a/src/hydrilla/proxy/web_ui/root.py
+++ b/src/hydrilla/proxy/web_ui/root.py
@@ -51,6 +51,7 @@ from ... import item_infos
 from ... import common_jinja_templates
 from .. import state as st
 from .. import http_messages
+from .. import self_doc
 from . import rules
 from . import repos
 from . import items
@@ -94,13 +95,13 @@ class WebUIAppImpl(_app.WebUIApp):
 
         self._haketilo_app_lock = Lock()
 
-        loader = jinja2.PackageLoader(__package__)
-        combined_loader = common_jinja_templates.combine_with_loaders([loader])
+        loaders = [jinja2.PackageLoader(__package__), self_doc.loader]
+        combined_loader = common_jinja_templates.combine_with_loaders(loaders)
 
         self.jinja_options = {
             **self.jinja_options,
             'loader':        combined_loader,
-            'autoescape':    jinja2.select_autoescape(['html.jinja']),
+            'autoescape':    jinja2.select_autoescape(['.jinja']),
             'lstrip_blocks': True,
             'extensions': [
                 *self.jinja_options.get('extensions', []),
@@ -118,6 +119,7 @@ class WebUIAppImpl(_app.WebUIApp):
         self.jinja_env.globals['ItemType']             = item_infos.ItemType
         self.jinja_env.globals['MappingUseMode']       = st.MappingUseMode
         self.jinja_env.globals['versions']             = versions
+        self.jinja_env.globals['doc_base_filename']    = 'doc_base.html.jinja'
 
         self.before_request(authenticate_by_referrer)
 
@@ -181,6 +183,16 @@ def home_post() -> werkzeug.Response:
 
     return flask.redirect(flask.url_for('.home'), 303)
 
+@home_bp.route('/doc/<path:page>', methods=['GET'])
+def home_doc(page: str) -> str:
+    if page not in self_doc.page_names:
+        flask.abort(404)
+
+    return flask.render_template(
+        f'{page}.html.jinja',
+        doc_output = 'html_hkt_mitm_it'
+    )
+
 blueprints_main = \
     (rules.bp, repos.bp, items.bp, items_import.bp, prompts.bp, home_bp)
 
-- 
cgit v1.2.3