From 7cf6ce9afb8af36d631a5bbaec2daa1da20d9f33 Mon Sep 17 00:00:00 2001
From: Emil Simeonov <emil@theliberatededge.org>
Date: Tue, 4 Aug 2026 10:28:02 +0200
Subject: [PATCH] fix: switch default network driver to slirp4netns (pasta TCP
 RST bug)

pasta's TCP proxy sends RST packets with wrong sequence numbers after
the first data packet, breaking TCP connections from Docker containers
to external hosts. slirp4netns doesn't have this bug.

Changes:
- Default gitea_runner_docker_rootless_net_driver changed to slirp4netns
- Port driver: 'implicit' for pasta, 'builtin' for slirp4netns
- daemon.json: DNS configured per driver (10.0.2.3 for pasta, 8.8.8.8 for slirp4netns)
- IPv6 only enabled for pasta (slirp4netns doesn't support IPv6)
- integration_test: retry service active check (handles slow startup)
---
 .vale/styles/Google/Anthropomorphism.yml      | 12 ++++
 .vale/styles/Google/Colons.yml                |  9 ++-
 .vale/styles/Google/DateFormat.yml            |  2 +-
 .vale/styles/Google/ExcessiveClaims.yml       | 14 ++++
 .vale/styles/Google/FirstPerson.yml           | 10 +--
 .vale/styles/Google/Headings.yml              |  7 +-
 .vale/styles/Google/Jargon.yml                | 13 ++++
 .vale/styles/Google/Latin.yml                 |  8 ++-
 .vale/styles/Google/OxfordComma.yml           | 10 ++-
 .vale/styles/Google/Parens.yml                | 10 ++-
 .vale/styles/Google/Timeless.yml              | 13 ++++
 .vale/styles/Google/Units.yml                 |  6 +-
 .vale/styles/Google/WordList.yml              | 57 +---------------
 .vale/styles/Google/WordListCase.yml          | 68 +++++++++++++++++++
 ansible/roles/gitea_runner/defaults/main.yml  |  9 ++-
 .../gitea_runner/tasks/integration_test.yml   |  5 +-
 .../gitea_runner/tasks/rootless_docker.yml    | 16 +++--
 17 files changed, 192 insertions(+), 77 deletions(-)
 create mode 100644 .vale/styles/Google/Anthropomorphism.yml
 create mode 100644 .vale/styles/Google/ExcessiveClaims.yml
 create mode 100644 .vale/styles/Google/Jargon.yml
 create mode 100644 .vale/styles/Google/Timeless.yml
 create mode 100644 .vale/styles/Google/WordListCase.yml

diff --git a/.vale/styles/Google/Anthropomorphism.yml b/.vale/styles/Google/Anthropomorphism.yml
new file mode 100644
index 0000000..36137a1
--- /dev/null
+++ b/.vale/styles/Google/Anthropomorphism.yml
@@ -0,0 +1,12 @@
+extends: existence
+message: "Don't attribute human qualities to software or hardware ('%s')."
+link: https://developers.google.com/style/anthropomorphism
+level: suggestion
+ignorecase: true
+# Limited to the two verbs the guide itself names. Broader lists (wants, knows,
+# thinks) can't tell a software subject from a human one: on a 950-file corpus
+# they produced 8 false positives ('the customer wants', 'your audience knows')
+# for every 2 real ones.
+tokens:
+  - sees
+  - tells
diff --git a/.vale/styles/Google/Colons.yml b/.vale/styles/Google/Colons.yml
index 4a027c3..98972b9 100644
--- a/.vale/styles/Google/Colons.yml
+++ b/.vale/styles/Google/Colons.yml
@@ -1,8 +1,13 @@
 extends: existence
 message: "'%s' should be in lowercase."
 link: 'https://developers.google.com/style/colons'
-nonword: true
 level: warning
 scope: sentence
+# The match is the word itself, not ': X', and `nonword` is off. Both are
+# required for a project Vocab to work: Vale compares accept.txt entries
+# against the matched text, and `nonword: true` opts out of that entirely.
+# So a proper noun after a colon can be exempted by adding it to accept.txt.
+# The guide's other exemption, notice labels, is handled by the lookbehinds;
+# headings are already excluded by `scope: sentence`. See issue #20.
 tokens:
-  - '(?<!:[^ ]+?):\s[A-Z]'
+  - '(?<!Note: )(?<!Caution: )(?<!Warning: )(?<!Success: )(?<=:\s)[A-Z]\w+'
diff --git a/.vale/styles/Google/DateFormat.yml b/.vale/styles/Google/DateFormat.yml
index e9d227f..b617310 100644
--- a/.vale/styles/Google/DateFormat.yml
+++ b/.vale/styles/Google/DateFormat.yml
@@ -6,4 +6,4 @@ level: error
 nonword: true
 tokens:
   - '\d{1,2}(?:\.|/)\d{1,2}(?:\.|/)\d{4}'
-  - '\d{1,2} (?:Jan(?:uary)?|Feb(?:ruary)?|Mar(?:ch)?|Apr(?:il)|May|Jun(?:e)|Jul(?:y)|Aug(?:ust)|Sep(?:tember)?|Oct(?:ober)|Nov(?:ember)?|Dec(?:ember)?) \d{4}'
+  - '\d{1,2} (?:Jan(?:uary)?|Feb(?:ruary)?|Mar(?:ch)?|Apr(?:il)?|May|Jun(?:e)?|Jul(?:y)?|Aug(?:ust)?|Sep(?:tember)?|Oct(?:ober)?|Nov(?:ember)?|Dec(?:ember)?) \d{4}'
diff --git a/.vale/styles/Google/ExcessiveClaims.yml b/.vale/styles/Google/ExcessiveClaims.yml
new file mode 100644
index 0000000..a44aca1
--- /dev/null
+++ b/.vale/styles/Google/ExcessiveClaims.yml
@@ -0,0 +1,14 @@
+extends: existence
+message: "Avoid the unverifiable claim '%s'."
+link: https://developers.google.com/style/excessive-claims
+level: suggestion
+ignorecase: true
+# The guide also names 'never', 'always', and 'ensure', but in technical writing
+# those are usually legitimate instructions ('never commit secrets') rather than
+# product claims: they accounted for 125 of 142 hits on a 950-file corpus.
+# 'best practices' is a fixed term, not a superlative.
+tokens:
+  - 'best(?! practices?)'
+  - simplest
+  - fastest
+  - guarantees?
diff --git a/.vale/styles/Google/FirstPerson.yml b/.vale/styles/Google/FirstPerson.yml
index 0b7b882..e367cbd 100644
--- a/.vale/styles/Google/FirstPerson.yml
+++ b/.vale/styles/Google/FirstPerson.yml
@@ -3,11 +3,13 @@ message: "Avoid first-person pronouns such as '%s'."
 link: 'https://developers.google.com/style/pronouns#personal-pronouns'
 ignorecase: true
 level: warning
-nonword: true
+# The 'I' tokens use lookaround rather than consuming the surrounding
+# whitespace. Matching ' I ' made the alert span cover both spaces, which shows
+# up as a too-wide underline in editors, and read as "such as ' I '". Dropping
+# `nonword` also lets a project Vocab apply, which it can't when set. See PR #50.
 tokens:
-  - (?:^|\s)I\s
-  - (?:^|\s)I,\s
-  - \bI'm\b
+  - '(?<=^|\s)I(?=[\s,])'
+  - "\\bI'm\\b"
   - \bme\b
   - \bmy\b
   - \bmine\b
diff --git a/.vale/styles/Google/Headings.yml b/.vale/styles/Google/Headings.yml
index c8d5be2..0a7f054 100644
--- a/.vale/styles/Google/Headings.yml
+++ b/.vale/styles/Google/Headings.yml
@@ -4,8 +4,11 @@ link: "https://developers.google.com/style/capitalization#capitalization-in-titl
 level: warning
 scope: heading
 match: $sentence
-indicators:
-  - ":"
+# No `indicators: [":"]` here. That makes Vale require a capital after a colon,
+# which is the Microsoft convention this rule was originally copied from. This
+# guide says the opposite: "the first word after a colon is generally
+# lowercase" (developers.google.com/style/colons), and Colons.yml enforces
+# exactly that. See issue #58.
 exceptions:
   - Azure
   - CLI
diff --git a/.vale/styles/Google/Jargon.yml b/.vale/styles/Google/Jargon.yml
new file mode 100644
index 0000000..c8cc8fb
--- /dev/null
+++ b/.vale/styles/Google/Jargon.yml
@@ -0,0 +1,13 @@
+extends: existence
+message: "Avoid the jargon '%s'."
+link: https://developers.google.com/style/jargon
+level: suggestion
+ignorecase: true
+# The guide also cites 'solution', 'support', and 'workload' as overloaded
+# terms, but those have ordinary technical meanings and accounted for every hit
+# on a 950-file corpus, so only the unambiguous figurative terms are listed.
+tokens:
+  - break-glass
+  - camel ?case
+  - out-of-the-box
+  - swim ?lane
diff --git a/.vale/styles/Google/Latin.yml b/.vale/styles/Google/Latin.yml
index ca03b91..325c096 100644
--- a/.vale/styles/Google/Latin.yml
+++ b/.vale/styles/Google/Latin.yml
@@ -6,6 +6,10 @@ level: error
 nonword: true
 action:
   name: replace
+# The delimiter is a lookahead so the replacement doesn't swallow the comma or
+# space that follows (issue #18). `$` is included so the abbreviation is still
+# caught at the end of a heading, table cell, or block, which accounted for 8
+# of 10 occurrences on a 950-file corpus.
 swap:
-  '\b(?:eg|e\.g\.)(?=[\s,;])': for example
-  '\b(?:ie|i\.e\.)(?=[\s,;])': that is
+  '\b(?:eg|e\.g\.)(?=[\s,;]|$)': for example
+  '\b(?:ie|i\.e\.)(?=[\s,;]|$)': that is
diff --git a/.vale/styles/Google/OxfordComma.yml b/.vale/styles/Google/OxfordComma.yml
index b9ba21e..a3ef78b 100644
--- a/.vale/styles/Google/OxfordComma.yml
+++ b/.vale/styles/Google/OxfordComma.yml
@@ -3,5 +3,13 @@ message: "Use the Oxford comma in '%s'."
 link: 'https://developers.google.com/style/commas'
 scope: sentence
 level: warning
+nonword: true
+# List items may be several words long, not just one. Two guards keep the
+# false-positive rate down: the item can't open with a clause-introducer
+# (', which ...', ', specifically ...'), and neither item may contain an
+# auxiliary verb, which is what separates a list from a compound predicate
+# (', it has some downsides and is officially discouraged.'). The trailing
+# anchor allows end-of-scope so list fragments ('Apples, pears or bananas')
+# are still caught.
 tokens:
-  - '(?:[^,]+,){1,}\s\w+\s(?:and|or)'
+  - ',\s(?!(?:which|who|whom|whose|that|where|when|while|because|since|although|though|if|unless|so|but|and|or|however|therefore|thus|specifically|especially|namely|then|take|see|note|consider|make|use|either|neither)\b)(?:(?!\b(?:is|are|was|were|has|have|had|be|been|being|will|would|can|could|should|may|might|must|do|does|did)\b)\w+ ){0,4}\w+ (?:and|or) (?:(?!\b(?:is|are|was|were|has|have|had|be|been|being|will|would|can|could|should|may|might|must|do|does|did)\b)\w+ ){0,4}\w+(?:[.?!]|$)'
diff --git a/.vale/styles/Google/Parens.yml b/.vale/styles/Google/Parens.yml
index 3b8711d..7e587eb 100644
--- a/.vale/styles/Google/Parens.yml
+++ b/.vale/styles/Google/Parens.yml
@@ -3,5 +3,13 @@ message: "Use parentheses judiciously."
 link: 'https://developers.google.com/style/parentheses'
 nonword: true
 level: suggestion
+# `[^)]` rather than `.+`: a greedy match ran from the first '(' on a line to
+# the last ')', so 'Text (one) and more (two).' produced a single alert
+# covering everything between them. See issue #30.
+# A bare 3-5 letter acronym is skipped: Acronyms.yml requires acronyms to be
+# defined as 'Spelled Out Term (ACRONYM)', so flagging those parentheses would
+# put the two rules in direct conflict. The acronym has to be the whole
+# parenthetical — '(NASA rocket program)' is an ordinary aside and still
+# flags. Length matches the {3,5} in Acronyms.yml. See PR #59.
 tokens:
-  - '\(.+\)'
+  - '\((?![A-Z]{3,5}\))[^)]+\)'
diff --git a/.vale/styles/Google/Timeless.yml b/.vale/styles/Google/Timeless.yml
new file mode 100644
index 0000000..943f449
--- /dev/null
+++ b/.vale/styles/Google/Timeless.yml
@@ -0,0 +1,13 @@
+extends: existence
+message: "Avoid time-based words like '%s' in product documentation."
+link: https://developers.google.com/style/timeless-documentation
+level: suggestion
+ignorecase: true
+# The guide also names 'now' and 'new', but both have common senses that aren't
+# time-anchored ('create a new project'): adding them took a 950-file corpus of
+# technical documentation from 14 hits to 117. 'recently' is left out too — every
+# hit in that corpus was the UI idiom 'recently used'.
+tokens:
+  - currently
+  - latest
+  - soon
diff --git a/.vale/styles/Google/Units.yml b/.vale/styles/Google/Units.yml
index 53522ab..4b4760d 100644
--- a/.vale/styles/Google/Units.yml
+++ b/.vale/styles/Google/Units.yml
@@ -4,5 +4,7 @@ link: "https://developers.google.com/style/units-of-measure"
 nonword: true
 level: error
 tokens:
-  - \b\d+(?:B|kB|MB|GB|TB)
-  - \b\d+(?:ns|ms|s|min|h|d)
+  - '\b\d+(?:B|kB|MB|GB|TB)\b'
+  - '\b\d+(?:ns|ms|min|h|d)\b'
+  # Seconds are split out so a decade ('1990s') isn't read as a unit.
+  - '\b\d+s\b(?<!\b(?:19|20)\d\ds\b)'
diff --git a/.vale/styles/Google/WordList.yml b/.vale/styles/Google/WordList.yml
index b3c6a40..25e925e 100644
--- a/.vale/styles/Google/WordList.yml
+++ b/.vale/styles/Google/WordList.yml
@@ -2,79 +2,28 @@ extends: substitution
 message: "Use '%s' instead of '%s'."
 link: "https://developers.google.com/style/word-list"
 level: warning
+# Case matters here: each key's own capitalization is what's being corrected,
+# so ignorecase would make these match their own replacements. The rest of the
+# word list lives in WordListCase.yml.
 ignorecase: false
 action:
   name: replace
 swap:
-  "(?:API Console|dev|developer) key": API key
-  "(?:cell ?phone|smart ?phone)": phone|mobile phone
-  "(?:dev|developer|APIs) console": API console
-  "(?:e-mail|Email|E-mail)": email
-  "(?:file ?path|path ?name)": path
-  "(?:kill|terminate|abort)": stop|exit|cancel|end
-  "(?:OAuth ?2|Oauth)": OAuth 2.0
-  "(?:ok|Okay)": OK|okay
-  "(?:WiFi|wifi)": Wi-Fi
-  '[\.]+apk': APK
-  '3\-D': 3D
-  'Google (?:I\-O|IO)': Google I/O
-  "tap (?:&|and) hold": touch & hold
-  "un(?:check|select)": clear
-  above: preceding
-  account name: username
-  action bar: app bar
-  admin: administrator
   Ajax: AJAX
-  a\.k\.a|aka: or|also known as
   Android device: Android-powered device
   android: Android
   API explorer: APIs Explorer
-  application: app
-  approx\.: approximately
   authN: authentication
   authZ: authorization
-  autoupdate: automatically update
-  cellular data: mobile data
-  cellular network: mobile network
-  chapter: documents|pages|sections
-  check box: checkbox
   CLI: command-line tool
-  click on: click|click in
   Cloud: Google Cloud Platform|GCP
   Container Engine: Kubernetes Engine
-  content type: media type
-  curated roles: predefined roles
-  data are: data is
   Developers Console: Google API Console|API Console
-  disabled?: turn off|off
-  ephemeral IP address: ephemeral external IP address
-  fewer data: less data
-  file name: filename
-  firewalls: firewall rules
-  functionality: capability|feature
   Google account: Google Account
   Google accounts: Google Accounts
   Googling: search with Google
-  grayed-out: unavailable
   HTTPs: HTTPS
-  in order to: to
-  ingest: import|load
   k8s: Kubernetes
-  long press: touch & hold
-  network IP address: internal IP address
-  omnibox: address bar
-  open-source: open source
-  overview screen: recents screen
-  regex: regular expression
   SHA1: SHA-1|HAS-SHA1
-  sign into: sign in to
-  sign-?on: single sign-on
-  static IP address: static external IP address
-  stylesheet: style sheet
-  synch: sync
-  tablename: table name
-  tablet: device
-  touch: tap
   url: URL
-  vs\.: versus
   World Wide Web: web
diff --git a/.vale/styles/Google/WordListCase.yml b/.vale/styles/Google/WordListCase.yml
new file mode 100644
index 0000000..0228496
--- /dev/null
+++ b/.vale/styles/Google/WordListCase.yml
@@ -0,0 +1,68 @@
+extends: substitution
+message: "Use '%s' instead of '%s'."
+link: "https://developers.google.com/style/word-list"
+level: warning
+# The case-insensitive half of the word list, so sentence-initial use is caught
+# ('Touch the screen', not only 'touch the screen'). Entries that must stay
+# case-sensitive are in WordList.yml.
+ignorecase: true
+action:
+  name: replace
+swap:
+  "(?:API Console|dev|developer) key": API key
+  "(?:cell ?phone|smart ?phone)": phone|mobile phone
+  "(?:dev|developer|APIs) console": API console
+  "(?:e-mail|Email|E-mail)": email
+  "(?:file ?path|path ?name)": path
+  "(?:kill|terminate|abort)": stop|exit|cancel|end
+  # Longest form first: with the shortest alternative leading, 'OAuth 2' matched
+  # only 'OAuth', so applying the suggestion produced 'OAuth 2.0 2'. The rule is
+  # already case-insensitive, so the inline (?i) is redundant. See issue #41.
+  '\bOauth2\.0\b|\bOAuth ?2\b(?!\.0)|\bOauth\b(?! ?2)': OAuth 2.0
+  "(?:ok|Okay)": OK|okay
+  "(?:WiFi|wifi)": Wi-Fi
+  '[\.]+apk': APK
+  '3\-D': 3D
+  'Google (?:I\-O|IO)': Google I/O
+  "tap (?:&|and) hold": touch & hold
+  "un(?:check|select)": clear
+  above: preceding
+  account name: username
+  action bar: app bar
+  admin: administrator
+  a\.k\.a|aka: or|also known as
+  application: app
+  approx\.: approximately
+  autoupdate: automatically update
+  cellular data: mobile data
+  cellular network: mobile network
+  chapter: documents|pages|sections
+  check box: checkbox
+  click on: click|click in
+  content type: media type
+  curated roles: predefined roles
+  data are: data is
+  disabled?: turn off|off
+  ephemeral IP address: ephemeral external IP address
+  fewer data: less data
+  file name: filename
+  firewalls: firewall rules
+  functionality: capability|feature
+  grayed-out: unavailable
+  in order to: to
+  ingest: import|load
+  long press: touch & hold
+  network IP address: internal IP address
+  omnibox: address bar
+  open-source: open source
+  overview screen: recents screen
+  regex: regular expression
+  sign into: sign in to
+  '(?<!single )sign-?on': single sign-on
+  static IP address: static external IP address
+  stylesheet: style sheet
+  synch: sync
+  tablename: table name
+  tablet: device
+  'touch(?! ?(?:&|and) hold)': tap
+  vs\.: versus
diff --git a/ansible/roles/gitea_runner/defaults/main.yml b/ansible/roles/gitea_runner/defaults/main.yml
index 87da8cd..e6ec8a5 100644
--- a/ansible/roles/gitea_runner/defaults/main.yml
+++ b/ansible/roles/gitea_runner/defaults/main.yml
@@ -64,9 +64,12 @@ gitea_runner_rootless_scripts_ref: "v28.5.1"
 # that dockerd-rootless-setuptool.sh (which derives BIN from its own dirname) finds them co-located.
 gitea_runner_rootless_scripts_install_dir: "/usr/bin"
 
-# Rootless Docker network driver: "pasta" (IPv6 support) or "slirp4netns" (IPv4 only)
-# pasta has proper outgoing IPv6 support; slirp4netns does not (known limitation).
-gitea_runner_docker_rootless_net_driver: "pasta"
+# Rootless Docker network driver: "slirp4netns" (default) or "pasta" (IPv6 support)
+# slirp4netns is the default because pasta has a TCP proxy bug that sends RST
+# packets with wrong sequence numbers, breaking TCP connections from Docker
+# containers to external hosts. slirp4netns doesn't have IPv6 support.
+# See: https://bugs.passt.top/show_bug.cgi?id=52
+gitea_runner_docker_rootless_net_driver: "slirp4netns"
 
 # IPv6 subnet for rootless Docker containers (ULA range, not routable on internet)
 gitea_runner_docker_ipv6_cidr: "fd00:dead:beef::/48"
diff --git a/ansible/roles/gitea_runner/tasks/integration_test.yml b/ansible/roles/gitea_runner/tasks/integration_test.yml
index b0e65c3..36a8c39 100644
--- a/ansible/roles/gitea_runner/tasks/integration_test.yml
+++ b/ansible/roles/gitea_runner/tasks/integration_test.yml
@@ -18,7 +18,7 @@
       else {} }}
   when: gitea_runner_file_stat.stat.exists | default(false) | bool
 
-- name: Verify runner user service active
+- name: Wait for runner user service to be active
   ansible.builtin.command: systemctl --user is-active gitea-runner
   become: true
   become_user: "{{ gitea_runner_service_user }}"
@@ -26,6 +26,9 @@
     XDG_RUNTIME_DIR: "/run/user/{{ gitea_runner_uid }}"
   register: gitea_runner_service_check
   changed_when: false
+  retries: 10
+  delay: 2
+  until: gitea_runner_service_check.stdout | default('') | trim == 'active'
   when:
     - gitea_runner_systemd_available.stat.exists
     - gitea_runner_docker_rootless_setup
diff --git a/ansible/roles/gitea_runner/tasks/rootless_docker.yml b/ansible/roles/gitea_runner/tasks/rootless_docker.yml
index ad17a6c..703cd8d 100644
--- a/ansible/roles/gitea_runner/tasks/rootless_docker.yml
+++ b/ansible/roles/gitea_runner/tasks/rootless_docker.yml
@@ -182,14 +182,16 @@
     group: "{{ gitea_runner_service_user }}"
   when: gitea_runner_docker_rootless_setup
 
-- name: Configure rootless Docker to use pasta with IPv6
+- name: Configure rootless Docker network driver
   ansible.builtin.copy:
     dest: "{{ gitea_runner_home }}/.config/systemd/user/docker.service.d/override.conf"
     content: |
       [Service]
       Environment="DOCKERD_ROOTLESS_ROOTLESSKIT_NET={{ gitea_runner_docker_rootless_net_driver }}"
-      Environment="DOCKERD_ROOTLESS_ROOTLESSKIT_PORT_DRIVER=implicit"
+      Environment="DOCKERD_ROOTLESS_ROOTLESSKIT_PORT_DRIVER={{ 'implicit' if gitea_runner_docker_rootless_net_driver == 'pasta' else 'builtin' }}"
+      {% if gitea_runner_docker_rootless_net_driver == 'pasta' %}
       Environment="DOCKERD_ROOTLESS_ROOTLESSKIT_FLAGS=--ipv6"
+      {% endif %}
     mode: "0644"
     owner: "{{ gitea_runner_service_user }}"
     group: "{{ gitea_runner_service_user }}"
@@ -207,14 +209,20 @@
     - gitea_runner_docker_rootless_setup
     - gitea_runner_docker_network_override is changed
 
-- name: Configure rootless Docker daemon with IPv6 enabled
+- name: Configure rootless Docker daemon
   ansible.builtin.copy:
     dest: "{{ gitea_runner_home }}/.config/docker/daemon.json"
     content: |
       {
+        {% if gitea_runner_docker_rootless_net_driver == 'pasta' %}
         "ipv6": true,
         "ip6tables": true,
-        "fixed-cidr-v6": "{{ gitea_runner_docker_ipv6_cidr }}"
+        "fixed-cidr-v6": "{{ gitea_runner_docker_ipv6_cidr }}",
+        "dns": ["10.0.2.3", "8.8.8.8"]
+        {% else %}
+        "ipv6": false,
+        "dns": ["8.8.8.8", "1.1.1.1"]
+        {% endif %}
       }
     mode: "0644"
     owner: "{{ gitea_runner_service_user }}"