mirror of
https://github.com/spantaleev/matrix-docker-ansible-deploy.git
synced 2026-09-16 21:00:09 +00:00
Reword the Molecule scenario comments
They were hard-wrapped at 80 characters, broke mid-parenthesis, and spent lines restating what the code below them does. Rewrapped at natural boundaries instead, with the narration dropped and only the reasons, gotchas and surprises kept. Section dividers stay - they delineate long plays rather than narrate them. Comments only; no scenario behaviour changes. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SEH3vxYSQ5SV4N5z61eyGT
This commit is contained in:
Slavi Pantaleev
co-authored by
Claude Opus 5
Claude Opus 5
parent
e2d3be504e
commit
c447e1528b
@@ -29,67 +29,57 @@ provisioner:
|
||||
all:
|
||||
matrix_bridge_hookshot_container_network: hookshot-molecule
|
||||
|
||||
# The stub prepare.yml stands up. Hookshot contacts it while starting;
|
||||
# it is not a real homeserver and nothing is asserted about it.
|
||||
# The stub prepare.yml stands up. Not a real homeserver, and nothing is asserted
|
||||
# about it.
|
||||
matrix_bridge_hookshot_homeserver_address: http://matrix.molecule.local:8008
|
||||
|
||||
# Appservice tokens. These are what Hookshot and the homeserver would
|
||||
# authenticate to each other with; here they only have to reach the
|
||||
# rendered configuration and the registration file.
|
||||
# Here these only have to reach the rendered configuration and the registration.
|
||||
matrix_bridge_hookshot_appservice_token: molecule_as_token_4f2a91
|
||||
matrix_bridge_hookshot_homeserver_token: molecule_hs_token_9b3e77
|
||||
|
||||
# Deliberately different from the role's default (`hookshot`), so the
|
||||
# registration's sender_localpart can only have come from the role.
|
||||
# prepare.yml tells the homeserver stub to claim this same user id.
|
||||
# Different from the role's default, so the registration's sender_localpart can only
|
||||
# have come from the role. prepare.yml tells the stub to claim this same user id.
|
||||
matrix_bridge_hookshot_bot_localpart: molecule-hookshot
|
||||
|
||||
# Hookshot's HTTP surface is the point of this scenario. Every port
|
||||
# below differs from BOTH the role's default and Hookshot's own, so an
|
||||
# answer on one of them can only mean the role's configuration reached
|
||||
# the process. verify.yml also asserts that nothing answers on the
|
||||
# defaults these replace (9993 appservice, 9000 webhooks, 9001 metrics).
|
||||
# Hookshot's HTTP surface is the point of this scenario. Every port below differs
|
||||
# from BOTH the role's default and Hookshot's own, so an answer can only mean the
|
||||
# role's configuration reached the process. verify.yml also asserts nothing answers
|
||||
# on the defaults these replace.
|
||||
matrix_bridge_hookshot_appservice_port: 9772
|
||||
matrix_bridge_hookshot_webhook_port: 9741
|
||||
|
||||
# Off in the role's defaults. Enabling it makes the role render a second
|
||||
# entry in Hookshot's `listeners` list, which is the cheapest listener to
|
||||
# assert *content* on: /metrics answers in a format nothing else would.
|
||||
# Off in the role's defaults. Enabling it renders a second entry in the `listeners`
|
||||
# list, and /metrics is the cheapest listener to assert *content* on.
|
||||
matrix_bridge_hookshot_metrics_enabled: true
|
||||
matrix_bridge_hookshot_metrics_port: 9752
|
||||
|
||||
# On in the role's defaults. Turned off here so that the absence of a
|
||||
# listener can be asserted too - the widgets port staying closed is what
|
||||
# tells "the role rendered the listener list" apart from "Hookshot binds
|
||||
# everything anyway".
|
||||
# On in the role's defaults. Off here so the absence of a listener can be asserted:
|
||||
# the widgets port staying closed is what tells "the role rendered the listener list"
|
||||
# apart from "Hookshot binds everything anyway".
|
||||
matrix_bridge_hookshot_widgets_enabled: false
|
||||
|
||||
# No third-party service is configured in this scenario - see the header
|
||||
# of verify.yml. GitLab is the one the role enables by default, so it is
|
||||
# explicitly switched off and its absence from the rendered config and
|
||||
# registration is asserted.
|
||||
# No third-party service is configured here; see the header of verify.yml.
|
||||
# GitLab is the one the role enables by default, so it is explicitly switched off.
|
||||
matrix_bridge_hookshot_gitlab_enabled: false
|
||||
|
||||
# The generic webhooks listener is the only part of Hookshot that needs
|
||||
# no account anywhere, so it is what this scenario exercises live. The
|
||||
# prefix differs from the role's default (`_webhooks_`).
|
||||
# The generic webhooks listener needs no account anywhere, so it is what this
|
||||
# scenario exercises live. The prefix differs from the role's default.
|
||||
matrix_bridge_hookshot_generic_userIdPrefix: _molecule_hook_ # noqa var-naming
|
||||
|
||||
# Neither the role's default (600) nor Hookshot's own (600).
|
||||
matrix_bridge_hookshot_feeds_pollIntervalSeconds: 907 # noqa var-naming
|
||||
|
||||
# The role defaults to `warn`; Hookshot itself defaults to `info`. This
|
||||
# is a third value, so finding it in config.yml cannot be a coincidence.
|
||||
# The role defaults to `warn`, Hookshot itself to `info`. A third value, so finding
|
||||
# it in config.yml cannot be a coincidence.
|
||||
matrix_bridge_hookshot_logging_level: debug
|
||||
|
||||
# Traefik is not deployed here, so the labels the role would render for
|
||||
# it are switched off and their absence is asserted instead.
|
||||
# Traefik is not deployed here, so the labels the role would render for it are
|
||||
# switched off and their absence is asserted instead.
|
||||
matrix_bridge_hookshot_container_labels_traefik_enabled: false
|
||||
|
||||
# verify.yml runs as its own play, where role defaults are out of scope,
|
||||
# so what it reads is pinned here. These two match the role's own
|
||||
# defaults on purpose - they name things (a path, a container) rather
|
||||
# than configure them, and nothing is asserted *about* them.
|
||||
# verify.yml runs as its own play, where role defaults are out of scope, so what it
|
||||
# reads is pinned here. These two match the role's own defaults on purpose: they name
|
||||
# things rather than configure them, and nothing is asserted *about* them.
|
||||
matrix_bridge_hookshot_base_path: /matrix/hookshot
|
||||
matrix_bridge_hookshot_identifier: matrix-hookshot
|
||||
env:
|
||||
|
||||
@@ -31,9 +31,8 @@
|
||||
docker_daemon_options:
|
||||
storage-driver: fuse-overlayfs
|
||||
|
||||
# The role's file tasks set owner/group by name and Ansible resolves those
|
||||
# through the passwd database, so they have to exist first. matrix-base
|
||||
# creates them in a real deployment.
|
||||
# The role's file tasks set owner/group by name, which Ansible resolves through the
|
||||
# passwd database, so they have to exist first. `matrix-base` creates them for real.
|
||||
- name: Ensure the matrix group exists
|
||||
ansible.builtin.group:
|
||||
name: "{{ matrix_group_name }}"
|
||||
|
||||
@@ -3,15 +3,14 @@
|
||||
# SPDX-License-Identifier: AGPL-3.0-or-later
|
||||
|
||||
---
|
||||
# What this proves: Hookshot starts, accepts the config.yml and registration.yml
|
||||
# the role rendered, and opens exactly the HTTP listeners that configuration
|
||||
# described - on the ports the role put there, and not on the ones it did not.
|
||||
# Proves Hookshot starts on the config.yml and registration.yml the role rendered,
|
||||
# and opens exactly the HTTP listeners that configuration described - on the ports
|
||||
# the role put there, and not on the ones it did not.
|
||||
#
|
||||
# What it deliberately does NOT do: configure GitHub, GitLab, Jira or Figma.
|
||||
# Every one of those needs an account and a credential on a third-party service,
|
||||
# which is the line where a scenario stops testing this repository and starts
|
||||
# testing a fake (see docs/molecule-testing.md). The generic webhooks listener
|
||||
# needs no credential from anyone, so it is the one that gets exercised live.
|
||||
# Deliberately does NOT configure GitHub, GitLab, Jira or Figma. Each needs an account
|
||||
# and a credential on a third-party service, which is where a scenario stops testing this
|
||||
# repository and starts testing a fake (see docs/molecule-testing.md). The generic webhooks
|
||||
# listener needs no credential from anyone, so it is the one exercised live.
|
||||
- name: Verify hookshot
|
||||
hosts: all
|
||||
become: true
|
||||
@@ -21,11 +20,10 @@
|
||||
gather_facts: false
|
||||
|
||||
tasks:
|
||||
# Read from the role's own defaults rather than pinned in molecule.yml, so
|
||||
# the version assertion below compares the running image against what the
|
||||
# role ships instead of against the scenario itself. The default ports come
|
||||
# from here for the same reason: the "these ports stay closed" assertion is
|
||||
# only meaningful against the ports the role would otherwise have used.
|
||||
# From the role's own defaults rather than pinned in molecule.yml, so the version
|
||||
# assertion compares the running image against what the role ships, not against the
|
||||
# scenario. The default ports come from here for the same reason: "these ports stay
|
||||
# closed" is only meaningful against the ports the role would otherwise have used.
|
||||
- name: Load the role's defaults under a separate name
|
||||
ansible.builtin.include_vars:
|
||||
file: "{{ lookup('env', 'MOLECULE_PROJECT_DIRECTORY') }}/defaults/main.yml"
|
||||
@@ -40,10 +38,9 @@
|
||||
delay: 5
|
||||
failed_when: false
|
||||
|
||||
# `Restart=always` means a bridge crash-looping on a configuration it cannot
|
||||
# read still reports `active`, so the restart counter is checked too. It is
|
||||
# asserted `is defined` because `| int` turns a missing property into 0 and
|
||||
# would pass vacuously.
|
||||
# `Restart=always` means a bridge crash-looping on unreadable config still reports
|
||||
# `active`, so the restart counter is checked too. Asserted `is defined` because
|
||||
# `| int` turns a missing property into 0 and would pass vacuously.
|
||||
- name: Assert the service is active and has not been restarting
|
||||
ansible.builtin.assert:
|
||||
that:
|
||||
@@ -70,9 +67,8 @@
|
||||
ansible.builtin.set_fact:
|
||||
hookshot_config: "{{ hookshot_config_file.content | b64decode | from_yaml }}"
|
||||
|
||||
# Each of these differs from what Hookshot would use on its own AND from
|
||||
# what the role defaults to, so finding them here means the role's
|
||||
# configuration is what Hookshot is running on rather than a coincidence.
|
||||
# Each differs from what Hookshot would use on its own AND from the role's defaults,
|
||||
# so finding them here rules out a coincidence.
|
||||
- name: Assert the rendered configuration carries this scenario's values
|
||||
ansible.builtin.assert:
|
||||
that:
|
||||
@@ -86,10 +82,9 @@
|
||||
fail_msg: "The rendered configuration does not carry the scenario's values"
|
||||
success_msg: "The rendered configuration carries the scenario's values"
|
||||
|
||||
# Hookshot's `listeners` list is the role's own construction: it decides
|
||||
# which resources get a port at all, from a handful of independent switches.
|
||||
# Getting this wrong is invisible in a "did it start" test, which is why it
|
||||
# is asserted as a whole rather than key by key.
|
||||
# The `listeners` list is the role's own construction, assembled from a handful of
|
||||
# independent switches. Getting it wrong is invisible in a "did it start" test,
|
||||
# hence asserting the whole shape rather than key by key.
|
||||
- name: Assert the role rendered exactly the listeners the scenario asked for
|
||||
ansible.builtin.assert:
|
||||
that:
|
||||
@@ -103,9 +98,8 @@
|
||||
vars:
|
||||
hookshot_listener_ports: "{{ hookshot_config.listeners | map(attribute='port') | map('int') | list }}"
|
||||
|
||||
# No third-party service is configured here, so none of their sections may
|
||||
# appear. GitLab is the interesting one: the role turns it ON by default, so
|
||||
# its absence is what proves the scenario's switch reached the template.
|
||||
# GitLab is the interesting one: the role turns it ON by default, so its absence
|
||||
# proves the scenario's switch reached the template.
|
||||
- name: Assert no third-party service section was rendered
|
||||
ansible.builtin.assert:
|
||||
that:
|
||||
@@ -131,9 +125,8 @@
|
||||
# The rendered registration
|
||||
# ------------------------------------------------------------------
|
||||
|
||||
# The registration file is the half of the appservice handshake the
|
||||
# homeserver reads. The role generates it, Hookshot only consumes it, so it
|
||||
# is worth checking on its own.
|
||||
# The role generates the registration; Hookshot only consumes it. Worth checking
|
||||
# on its own, as it is the half of the handshake the homeserver reads.
|
||||
- name: Read the appservice registration the role rendered
|
||||
ansible.builtin.slurp:
|
||||
src: "{{ matrix_bridge_hookshot_base_path }}/registration.yml"
|
||||
@@ -143,9 +136,8 @@
|
||||
ansible.builtin.set_fact:
|
||||
hookshot_registration: "{{ hookshot_registration_file.content | b64decode | from_yaml }}"
|
||||
|
||||
# `url` is where the homeserver would push transactions, and the role builds
|
||||
# it out of the container name and the appservice port. It has to agree with
|
||||
# `bridge.port` in config.yml or the two halves would silently disagree.
|
||||
# `url` is built from the container name and the appservice port. It has to agree
|
||||
# with `bridge.port` in config.yml, or the two halves silently disagree.
|
||||
- name: Assert the registration carries the scenario's tokens, bot and callback URL
|
||||
ansible.builtin.assert:
|
||||
that:
|
||||
@@ -156,9 +148,9 @@
|
||||
fail_msg: "The appservice registration does not carry the scenario's tokens, bot and callback URL"
|
||||
success_msg: "The appservice registration carries the scenario's tokens, bot and callback URL"
|
||||
|
||||
# The user namespace is derived from the generic webhook prefix, and the
|
||||
# GitLab namespace is conditional on the service being enabled - so this
|
||||
# checks that the two switches reach the registration, not just config.yml.
|
||||
# The user namespace derives from the generic webhook prefix, and the GitLab namespace
|
||||
# is conditional on that service being enabled. Checks both switches reach the
|
||||
# registration, not just config.yml.
|
||||
- name: Assert the registration namespaces follow the enabled services
|
||||
ansible.builtin.assert:
|
||||
that:
|
||||
@@ -176,8 +168,8 @@
|
||||
# The listeners, live
|
||||
# ------------------------------------------------------------------
|
||||
|
||||
# A helper container is used because the role publishes no host port, exactly
|
||||
# as in a real deployment; see docs/molecule-testing.md.
|
||||
# A helper container, because the role publishes no host port - exactly as in a real
|
||||
# deployment. See docs/molecule-testing.md.
|
||||
- name: Wait for the webhooks listener to answer on the port the role configured
|
||||
ansible.builtin.command:
|
||||
argv:
|
||||
@@ -205,11 +197,10 @@
|
||||
delay: 5
|
||||
failed_when: false
|
||||
|
||||
# Hookshot answers an unknown webhook id from its generic-webhook handler,
|
||||
# with a JSON body no other component would produce. An Express "Cannot POST"
|
||||
# page here would mean the port is Hookshot's but the generic webhooks
|
||||
# service was never mounted on it; a refused connection would mean the
|
||||
# listener the role described was never opened at all.
|
||||
# An unknown webhook id draws a JSON body from the generic-webhook handler that no
|
||||
# other component would produce. An Express "Cannot POST" page would mean the port is
|
||||
# Hookshot's but the generic webhooks service was never mounted on it; a refused
|
||||
# connection would mean the listener was never opened at all.
|
||||
- name: Assert the generic webhooks service is mounted on that listener
|
||||
ansible.builtin.assert:
|
||||
that:
|
||||
@@ -222,9 +213,8 @@
|
||||
({{ hookshot_webhooks_probe.stdout | default('no output') }})
|
||||
success_msg: "The generic webhooks service answers on the port the role configured"
|
||||
|
||||
# Metrics are OFF in the role's defaults, so this listener exists only
|
||||
# because the scenario asked for it - and /metrics answers in a format
|
||||
# nothing else on that port could have produced.
|
||||
# Metrics are OFF in the role's defaults, so this listener exists only because the
|
||||
# scenario asked for it.
|
||||
- name: Probe the metrics listener on the port the role configured
|
||||
ansible.builtin.command:
|
||||
argv:
|
||||
@@ -253,8 +243,8 @@
|
||||
metrics ({{ hookshot_metrics_probe.stdout | default('no output') | truncate(200) }})
|
||||
success_msg: "The metrics listener serves Hookshot's own metrics"
|
||||
|
||||
# The appservice port is not in `listeners` - it comes from `bridge.port` -
|
||||
# so it is a separate socket, opened by a separate part of the config.
|
||||
# The appservice port is not in `listeners`; it comes from `bridge.port`.
|
||||
# A separate socket, opened by a separate part of the config.
|
||||
- name: Probe the appservice port the role configured
|
||||
ansible.builtin.command:
|
||||
argv:
|
||||
@@ -284,10 +274,10 @@
|
||||
({{ hookshot_appservice_probe.stdout | default('no output') }})
|
||||
success_msg: "The appservice API answers on the port the role configured"
|
||||
|
||||
# The other half of the story. Every port above is one the scenario chose;
|
||||
# these are the ones the role and Hookshot would have used if the scenario's
|
||||
# configuration had never reached the process. If any of them answers, then
|
||||
# a passing probe above proves much less than it looks like it does.
|
||||
# The other half of the story. Every port above is one the scenario chose; these are
|
||||
# the ones the role and Hookshot would have used had the scenario's configuration never
|
||||
# reached the process. If any of them answers, the probes above prove much less than
|
||||
# they appear to.
|
||||
- name: Probe the ports the role's defaults would have used
|
||||
ansible.builtin.command:
|
||||
argv:
|
||||
|
||||
Reference in New Issue
Block a user