tools: add editor and lint configuration

Add a standardized vscode configuration that should lead to a more consistent code base. Additionally, switch to markdownlint-cli that is well supported in vs code and other editors. The rules are kept the same, but we extend linting to our documentation to. To satisfy the linter, we switch to myst parser for sphinx which allows us to drop the hacky html tags in the markdown files. Myst is as powerful as RST with a more sane syntax.
scionproto · Mar 14, 2023 · 2f31150 · 2f31150
1 parent 1fd088b
commit 2f31150
Show file tree

Hide file tree

Showing 16 changed files with 212 additions and 67 deletions.
diff --git a/.github/ISSUE_TEMPLATE/01-proposal.md b/.github/ISSUE_TEMPLATE/01-proposal.md
@@ -8,4 +8,3 @@ labels: i/proposal
 Our proposal process is documented here:
 https://docs.scion.org/en/latest/contribute.html#change-proposal-process
 -->
-
diff --git a/.gitignore b/.gitignore
@@ -32,7 +32,9 @@ __pycache__
 
 # VSCode folder
 #########################
-.vscode/
+.vscode/*
+!.vscode/settings.json
+!.vscode/extensions.json
 
 # build files
 #########################

diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc
@@ -0,0 +1,29 @@
+{
+    "globs": ["**/*.md"],
+    "ignores": [
+        "**/node_modules/**",
+        "**/venv/**",
+        "licenses/data/**",
+        "**/_build/**"
+    ],
+    "config": {
+        "default": true,
+        "MD013": {
+            "line_length": 100,
+            "code_blocks": false,
+            "tables": false
+        },
+        "MD007": {
+            "indent": 4
+        },
+        "MD024": {
+            "allow_different_nesting": true
+        },
+        "MD030": {
+            "ol_multi": 1,
+            "ul_multi": 1,
+            "ol_single": 1,
+            "ul_single": 1
+        }
+    }
+}
diff --git a/.vscode/extensions.json b/.vscode/extensions.json
@@ -0,0 +1,23 @@
+{
+    "recommendations": [
+        "DavidAnson.vscode-markdownlint",
+        "eamodio.gitlens",
+        "esbenp.prettier-vscode",
+        "GitHub.vscode-pull-request-github",
+        "golang.go",
+        "ms-azuretools.vscode-docker",
+        "ms-python.isort",
+        "ms-python.vscode-pylance",
+        "ms-vscode-remote.remote-containers",
+        "ms-vscode-remote.remote-ssh",
+        "ms-vscode-remote.remote-ssh-edit",
+        "ms-vscode.remote-explorer",
+        "ms-vsliveshare.vsliveshare",
+        "mhutchie.git-graph",
+        "shardulm94.trailing-spaces",
+        "stkb.rewrap",
+        "stackbuild.bazel-stack-vscode",
+        "wayou.vscode-todo-highlight",
+        "windmilleng.vscode-go-autotest"
+    ]
+}
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -0,0 +1,99 @@
+{
+    //////////////////////
+    // Editor
+    //////////////////////
+    "rewrap.wrappingColumn": 80,
+    "breadcrumbs.enabled": true,
+    "files.eol": "\n",
+    "files.insertFinalNewline": true,
+
+    //////////////////////
+    // Go
+    //////////////////////
+    "[go]": {
+        "editor.snippetSuggestions": "none",
+        "editor.formatOnSave": true,
+        "editor.codeActionsOnSave": {
+            "source.organizeImports": true
+        }
+    },
+    "gopls": {
+        "formatting.local": "github.com/scionproto/scion",
+        "usePlaceholders": true, // add parameter placeholders when completing a function
+        "build.directoryFilters": [
+            "-bazel-bin",
+            "-bazel-out",
+            "-venv",
+            "-bazel-testlogs"
+        ],
+        // Experimental settings
+        "completeUnimported": true, // autocomplete unimported packages
+        "deepCompletion": true // enable deep completion
+    },
+
+    //////////////////////
+    // Python
+    //////////////////////
+    "python.languageServer": "Pylance",
+    "python.analysis.exclude": [
+        "**/.bazel-*/**",
+        "**/.idea/**",
+        "**/.git/objects/**",
+        "**/.git/subtree-cache/**",
+        "**/.venvs/**",
+        "**/bazel-*/**"
+    ],
+    "python.envFile": "${workspaceFolder}/.vscode/.env",
+
+    //////////////////////
+    // Prettier
+    //////////////////////
+    "prettier.documentSelectors": ["**/*.json"],
+    "[json]": {
+        "editor.defaultFormatter": "esbenp.prettier-vscode"
+    },
+    "[jsonc]": {
+        "editor.defaultFormatter": "esbenp.prettier-vscode"
+    },
+
+    //////////////////////
+    // Files, Search
+    //////////////////////
+    "files.associations": {
+        "*.topo": "yaml"
+    },
+    "files.watcherExclude": {
+        "**/.bazel-*/**": true,
+        "**/.idea/**": true,
+        "**/.git/objects/**": true,
+        "**/.git/subtree-cache/**": true,
+        "**/.venvs/**": true,
+        "**/bazel-*/**": true,
+        "**/gen-cache/**": true,
+        "gen*/**": true,
+        "**/logs/**": true,
+        "**/node_modules/**": true
+    },
+    "search.exclude": {
+        "**/.bazel-*/**": true,
+        "**/.idea/**": true,
+        "**/.git/objects/**": true,
+        "**/.git/subtree-cache/**": true,
+        "**/.venvs/**": true,
+        "**/bazel-*/**": true,
+        "**/gen-cache/**": true,
+        "**/logs/**": true,
+        "**/node_modules/**": true
+    },
+    "search.followSymlinks": false,
+
+    //////////////////////
+    // Docker
+    //////////////////////
+    "docker.containers.sortBy": "Label",
+
+    //////////////////////
+    // GitHub
+    //////////////////////
+    "githubPullRequests.pullBranch": "never"
+}
diff --git a/Makefile b/Makefile
@@ -117,5 +117,4 @@ lint-doc: lint-doc-mdlint
 
 lint-doc-mdlint:
 	$(info ==> $@)
-	@FILES=$$(find -type f -iname '*.md' -not -path "./rules_openapi/tools/node_modules/*" -not -path "./.github/**/*" | grep -vf tools/md/skipped); \
-		docker run --rm -v ${PWD}:/data -v ${PWD}/tools/md/mdlintstyle.rb:/style.rb $$(docker build -q tools/md) $${FILES} -s /style.rb
+	docker run -v ${PWD}:/workdir davidanson/markdownlint-cli2:v0.6.0
diff --git a/doc/.markdownlint-cli2.jsonc b/doc/.markdownlint-cli2.jsonc
@@ -0,0 +1,6 @@
+{
+    "extends": "../.markdownlint-cli2.jsonc",
+    "config": {
+        "MD041": false
+    }
+}
diff --git a/doc/BeaconService.md b/doc/BeaconService.md
@@ -1,12 +1,10 @@
 # Beacon Service Design
 
-
+:::{warning}
 
----
-⚠️  **NOTE** ⚠️<br/>
 Outdated contents! This document is kept for historical purpose.
 
----
+:::
 
 ## Overview
 

diff --git a/doc/ColibriService.md b/doc/ColibriService.md
@@ -60,8 +60,8 @@ If the current AS is the last one, do nothing.
 #### Handle a Setup Response
 
 The response message originated from another AS's *COS* handling a request.
-The request is forwarded from AS<sub>i</sub> to AS<sub>i+1</sub>, where AS<sub>i+1</sub> is the
-next AS after AS<sub>i</sub> in the path of the reservation.
+The request is forwarded from $AS_i$ to $AS_{i+1}$, where $AS_{i+1}$ is the
+next AS after $AS_{i}$ in the path of the reservation.
 
 1. The store saves the reservation as final.
 1. If this AS is the first one in the reservation path (aka *reservation initiator*),
@@ -75,7 +75,7 @@ next AS after AS<sub>i</sub> in the path of the reservation.
 
 1. The *COS* store is queried to admit the segment reservation.
 1. The store decides the admission for the reservation (how much bandwidth). It uses the
-   _traffic_matrix_ from the configuration package.
+   *traffic_matrix* from the configuration package.
 1. The store saves an intermediate reservation entry in the DB.
 1. If this AS is the last one in the path, the *COS* store saves the reservation as final
    and notifies the previous AS in the path with a reservation response.
@@ -89,7 +89,7 @@ ASes. Whenever that configuration changes, the service should be notified.
 1. The service triggers the creation of a new segment reservation at boot time and whenever
    the segment reservation configuration file changes.
 1. The service reads the configuration file and creates a segment reservation request per each entry.
-    * The path used in the request must be obtained using the _path predicate_ in the configuration.
+    * The path used in the request must be obtained using the *path predicate* in the configuration.
 1. The store in the *COS* saves the intermediate request and sends the request to the next AS
    in the path.
 1. If there is a timeout, this store will send a cleanup request to the next AS in the path.

diff --git a/doc/EPIC.md b/doc/EPIC.md
@@ -26,12 +26,12 @@ plane packets of other hosts. Because the MACs are static, once
 observed MACs for some path can be reused by the adversary to send
 arbitrarily many other packets (until the authenticators expire).
 
-The EPIC (Every Packet Is Checked) protocol [[1]](#1) solves this
+The EPIC (Every Packet Is Checked) protocol {ref}`[1]<references>` solves this
 problem by introducing per-packet MACs.
 Even if an adversary is able to discover the MACs for one packet, he
 cannot reuse the MACs to send any other traffic.
 The improved path authorization provided by EPIC is especially
-important for hidden paths [[2]](#2). Hidden paths are paths which
+important for hidden paths {ref}`[2]<references>`. Hidden paths are paths which
 are not publicly announced, but only communicated to a group of
 authorized sources. If one of those sources sends traffic on the
 hidden path using SCION path type packets, an on-path adversary can
@@ -82,19 +82,17 @@ meaningful level of security:
   hidden path, the last two ASes employ one of two different
   strategies in the data plane:
 
-    - Only allow EPIC-HP path type traffic. See use case "Highly
-      Secure Hidden Paths" [here](#HighlySecureHiddenPaths). The path
-      type filtering is further explained [here](#PathTypeFiltering).
-    - Prioritize EPIC-HP path type traffic. See use case "DOS-Secure
-      Hidden Paths" [here](#DOSSecureHiddenPaths).
+    - Only allow EPIC-HP path type traffic. See use case {ref}`HighlySecureHiddenPaths`.
+      The path type filtering is further explained in {ref}`PathTypeFiltering`.
+    - Prioritize EPIC-HP path type traffic. See use case {ref}`DOSSecureHiddenPaths`.
 
 - The last two ASes of the hidden path have a duplicate-suppression
-  system in place [[3]](#3). This prohibits DOS attacks based on replayed
+  system in place {ref}`[3]<references>`. This prohibits DOS attacks based on replayed
   packets.
 
 ### Example
 
-![](fig/EPIC/path-type-filtering-small.png).
+![path type filtering figure](fig/EPIC/path-type-filtering-small.png).
 
 Here, AS 6 is the AS protected by the hidden path (blue lines). The
 hidden path terminates at AS 6 (represented by black dot), so AS 6
@@ -156,9 +154,11 @@ The last AS on the path needs to distribute the authenticators to
 the set of trusted sources that should be able to send EPIC-HP
 traffic over the hidden link. This can be done over any secure
 channel, for example using secure end-to-end protocols, out-of-band
-communication, or the dedicated hidden path infrastructure [[2]](#2).
+communication, or the dedicated hidden path infrastructure {ref}`[2]<references>`.
 
-### <a id="PathTypeFiltering"></a> Path Type Filtering
+(PathTypeFiltering)=
+
+### Path Type Filtering
 
 Network operators should be able to clearly define which kind of
 traffic (SCION, EPIC-HP, COLIBRI, and other protocols) they want to
@@ -174,7 +174,8 @@ not apply any filtering for traffic from interface 2 to interface 1.
 
 There are two main applications for EPIC-HP:
 
-<a id="HighlySecureHiddenPaths"></a>
+(HighlySecureHiddenPaths)=
+
 ### Highly Secure Hidden Paths
 
 The last and penultimate ASes on the hidden path only allow EPIC-HP
@@ -195,7 +196,8 @@ packets towards hosts in other ASes, but that those hosts can not
 send a response back if they do not have the necessary
 authenticators.
 
-<a id="DOSSecureHiddenPaths"></a>
+(DOSSecureHiddenPaths)=
+
 ### DoS-Secure Hidden Paths
 
 The last and penultimate ASes on the hidden path allow EPIC-HP and
@@ -212,20 +214,22 @@ packets towards hosts in other ASes, and those hosts can reply
 with SCION path type traffic when they do not have the necessary
 authenticators to send back EPIC-HP traffic.
 
+(references)=
+
 ## References
 
-<a id="1">[1]</a>
-M. Legner, T. Klenze, M. Wyss, C. Sprenger, A. Perrig. (2020) <br>
-EPIC: Every Packet Is Checked in the Data Plane of a Path-Aware Internet <br>
+[1]
+M. Legner, T. Klenze, M. Wyss, C. Sprenger, A. Perrig. (2020)  
+EPIC: Every Packet Is Checked in the Data Plane of a Path-Aware Internet  
 Proceedings of the USENIX Security Symposium
 [[Link]](https://netsec.ethz.ch/publications/papers/Legner_Usenix2020_EPIC.pdf)
 
-<a id="2">[2]</a>
+[2]
 Design Document for the Hidden Path Infrastructure
 [[Link]](hidden-paths)
 
-<a id="3">[3]</a>
-T. Lee, C. Pappas, A. Perrig, V. Gligor, and Y. Hu. (2017) <br>
-The Case for In-Network Replay Suppression <br>
+[3]
+T. Lee, C. Pappas, A. Perrig, V. Gligor, and Y. Hu. (2017)  
+The Case for In-Network Replay Suppression  
 Proceedings of the ACM Asia Conference on Computer and Communications Security
 [[Link]](https://netsec.ethz.ch/publications/papers/replay2017.pdf)
diff --git a/doc/PathPolicy.md b/doc/PathPolicy.md
@@ -3,6 +3,8 @@
 The path policy language will be used by the path server, SCIOND and the beacon server for different
 but overlapping purposes.
 
+(HopPredicate)=
+
 ## Hop Predicate (HP)
 
 A hop predicate is of the form **ISD-AS#IF,IF**. The first **IF** means the inbound interface
@@ -30,10 +32,10 @@ Examples:
 
 A policy is defined by a policy object. It can have the following attributes:
 
-- [`extends`](#Extends) (list of extended policies)
-- [`acl`](#ACL) (list of HPs, preceded by `+` or `-`)
-- [`sequence`](#Sequence) (space separated list of HPs, may contain operators)
-- [`options`](#Options) (list of option policies)
+- [`extends`](#extends) (list of extended policies)
+- [`acl`](#acl) (list of HPs, preceded by `+` or `-`)
+- [`sequence`](#sequence) (space separated list of HPs, may contain operators)
+- [`options`](#options) (list of option policies)
     - `weight` (importance level, only valid under `options`)
     - `policy` (a policy object)
 
@@ -63,7 +65,8 @@ Planned:
 - `-` (deny predicate)
 
 The ACL can be used to deny (blacklist) or allow (whitelist) ISDs, ASes and IFs. A deny entry is of
-the following form `- ISD-AS#IF`, where the second part is a [HP](#HP). If a deny entry matches any
+the following form `- ISD-AS#IF`, where the second part is a
+{ref}`HopPredicate`. If a deny entry matches any
 hop on a path, the path is not allowed.
 
 An allow entry uses `+` with a HP, ie. `+ ISD-AS#IF`. For a path to be allowed, every hop of the
@@ -101,7 +104,7 @@ Planned:
 - `!` (logical NOT)
 - `&` (logical AND)
 
-The sequence is a string of space separated HPs. The [operators](#Operators) can be used for
+The sequence is a string of space separated HPs. The [operators](#operators) can be used for
 advanced interface sequences.
 
 The following example specifies a path from any interface in AS _1-ff00:0:133_ to two subsequent