You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
support network.ingress.hostLoopback: "allow" without a caller-supplied forwarding list: the workload reaches host loopback through its gateway, subject to the egress policy, and the host reaches every TCP and UDP port on which the workload listens on a non-loopback address, on host 127.0.0.1 or ::1 alone
build on the private-network ingress mechanism of Support private-network inbound access #275 instead of a separate publisher: the guest's nvx-ingress announcer now also runs for virtnet_ingress=host-loopback, and guest-loopback listeners stay private
lower hostLoopback: allow and hostLoopbackForwards through nvx-rs and the ACI Edge Sandboxes OpenVMM backend to --host-loopback allow and up to 64 explicit TCP or UDP forwards; forwards need host-loopback access allowed, an egress default of allow, and no deny rule over the guest network, each protocol's host ports and guest ports appear at most once, and the sandbox record keeps them
egress rules that deny a gateway port also deny it at the addresses at which OpenVMM presents host peers to the guest, and those addresses lie inside the guest's subnet of each family, so the guest answers host clients over IPv6 loopback from its own address under any egress policy
Pinned revision: 7f225e2cd635bbd1e1839e587e659996433396c8, two commits past dd8def143ddcbbf174719d851cd5f28cd07489a7, the private-network ingress revision that dev pins
Relationship: replaces the earlier pin 1866919502ac4188cf66445bf3062b9f8409884c, whose separate publication protocol conflicted with Support private-network inbound access #275's. This is a re-implementation on Support private-network inbound access #275's mechanism, not a rebase, so it claims neither tree nor patch equivalence with the earlier revision. The roadmap index records positions 316 and 317
Changes
guest/common/init starts nvx-ingress for virtnet_ingress=allow and virtnet_ingress=host-loopback
nvx-rs: NetworkPolicy gains the host-loopback access and validated loopback forwards, and the fake OpenVMM accepts --host-loopback-forward
ACI Edge Sandboxes: the OpenVMM backend advertises host-loopback allow and forwards (SandboxSpec::with_host_loopback_forward, AciEdgeSandbox::provision_with) and persists the forwards in the sandbox record without changing its format version
the host-loopback-policy microVM scenario checks, under an egress default of deny, the token and announcer, host clients of published IPv4 and IPv6 TCP listeners, UDP exchanges over IPv4 and IPv6 loopback, an explicit forward, guest-loopback privacy, and the snapshot rejection
ACI tests: launch arguments and rejections against the fake OpenVMM, host_loopback_access_is_bidirectional end to end, and the agent guest test
documentation: doc/run.md, doc/usage.md, the design documents, the ACI README, and the OpenVMM roadmap index
Review follow-ups
54b80b44: nvx-rs rejects a second forward of one protocol to the same guest port, which OpenVMM keys by guest port and could not bind
87be52ce and 3f9e5f0d: host-to-guest UDP over ::1 got no reply under an active egress policy, because OpenVMM presented host peers at link-local addresses that the guest answered from its link-local address. consomme: present IPv6 host peers inside the static subnet nanvix/openvmm#135 presents them inside the guest's subnet instead, and the scenario now exchanges UDP over IPv6 loopback; it fails with the previous pin
5cfba311: nvx-rs rejects host-loopback access for a /30 guest network, which holds only the gateway and the guest, so OpenVMM presents IPv4 host peers at the gateway there and IPv4 UDP replies to the host would not return through the published port; the ACI OpenVMM backend reports it as policy_validation
Validation
On 5cfba311e9b5f4a6c59a815899830154fc2446d1, on Windows: the nvx-rs and ACI Edge Sandboxes gates (cargo fmt --check, clippy for all features and for the library without default features, tests for all features and default features, docs with -D warnings, and the MSRV 1.89 checks).
On 3f9e5f0dcb10236a3d041b84ac634ccaf8631d1a, whose successor changes only Rust validation and documentation, on Windows:
python scripts\nvx.py verify
ruff check and ruff format --check for scripts and .github/specula; pyright for Linux and Windows: 0 errors
python -m unittest scripts/test_microvm_tests.py scripts/test_guest_ingress.py: 198 tests OK (14 skipped on Windows)
Windows/WHP with OpenVMM built from 7f225e2c: test-microvmhost-loopback-policy, private-network-ingress, ipv6-egress-policy, directional-network-policy, network-snapshot, and endpoint-policy-snapshot passed, and test-aci-edge-sandboxes passed 18/18
On 54b80b44: the same nvx-rs and ACI Edge Sandboxes gates. Before the rebase onto the current dev, whose new commits change neither guest/, the microVM scenarios, nor nvx-rs: ShellCheck and shfmt for guest/common/init.
On Windows, a host listener that binds every host address after a publication, without asking for exclusive use of the port, succeeds and gets the port's traffic except loopback, which stays with the guest, as it would with any host process listening on loopback alone. Linux refuses that binding. doc/run.md documents this.
A /30 IPv4 guest network has no free address for an IPv4 host peer, so OpenVMM presents it at the gateway, as it did before this PR, and the guest's UDP replies to host clients over IPv4 loopback do not return through the published port. nvx-rs and therefore ACI Edge Sandboxes reject host-loopback access for a /30; direct OpenVMM and nvx.py use accept it, and doc/run.md documents the limit.
Release port reservation only after guest listener is ready
aci_edge_sandboxes/tests/agent_guest.rs:2570
The selected port is released before the sandbox boots, leaving a long window for another host process to claim it. In that case OpenVMM correctly leaves the existing owner in place, but this test times out or connects to the unrelated service. Keep a loopback reservation through boot and guest-listener readiness, then release it so the publisher can claim the port on its next announcement.
Nothing in CI checked the repository's relative Markdown links. #529
moved the design documentation, numbered its sections, and retargeted
every inbound link by hand, while an older link had already broken: the
MXC integration table in aci_edge_sandboxes/README.md linked the anchor
native-proxy-and-forwarded-ports of a heading that #512 had renamed to
"Native proxy and host loopback". GitHub opens a page at its top when an
anchor is missing, so such links break silently, and so do comments
that cite a document by path, as the citations of the removed time ABI
specification did (#562).
Add scripts/check_markdown_links.py, a standard-library check, and run
it in check-quality, whose job runs for every pull request that is
ready for review, including the documentation-only ones that are most
likely to break a link:
- It resolves every relative link and image target of the tracked
Markdown files, whether an inline link, a reference definition, or an
HTML href or src attribute, against the files that Git tracks, so a
target that is untracked or differs in case, which GitHub cannot
serve, fails too. A directory resolves, and its anchors are those of
its README. An empty target, such as that of [Self](), links to its
own document.
- It resolves each anchor against the heading slugs that GitHub
generates, including the numeric suffixes of repeated headings, and
against HTML id and name attributes. Other files accept only line
anchors, such as #L10, within their length.
- It scans the blocks of each document as CommonMark nests them in
block quotes and list items, with lazy continuation lines, so that,
as on GitHub, front matter, fenced and indented code, code spans, HTML
comments and blocks, escaped brackets, and invalid reference
definitions hold no links, while the definitions and headings inside
block quotes and list items count.
- Links into the openvmm submodule resolve against its pinned commit
when it is checked out and are skipped otherwise, as in the quality
job, whose checkout does not fetch submodules.
- It also resolves, from the repository root, every doc/ path, with any
anchor, that a tracked text file mentions. DOC_PATH_FIXTURES lists
the test fixtures that name missing documents, such as doc/notes.md
in scripts/test_nvx_tools.py, and an entry that its file no longer
needs fails the check. A mention followed by a character that could
extend the path, such as the * of a pattern, is ambiguous and is
skipped.
- It reports each problem with its file and line, as an error
annotation in GitHub Actions, and then exits with status 1.
scripts/test_markdown_links.py covers the slugs, the parsing, the
resolution in temporary repositories, including a submodule, the
fixtures, and the command line, and validate-nvx runs it on Linux and
Windows.
Retarget the README link to native-proxy-and-host-loopback, the only
broken link that the check found, and document the check in
doc/contribute.md, doc/setup.md, and doc/project-structure.md.
Fixes#563
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Nothing in CI checked the repository's relative Markdown links. #529
moved the design documentation, numbered its sections, and retargeted
every inbound link by hand, while an older link had already broken: the
MXC integration table in aci_edge_sandboxes/README.md linked the anchor
native-proxy-and-forwarded-ports of a heading that #512 had renamed to
"Native proxy and host loopback". GitHub opens a page at its top when an
anchor is missing, so such links break silently, and so do comments
that cite a document by path, as the citations of the removed time ABI
specification did (#562).
Add scripts/check_markdown_links.py, a standard-library check, and run
it in check-quality, whose job runs for every pull request that is
ready for review, including the documentation-only ones that are most
likely to break a link:
- It resolves every relative link and image target of the tracked
Markdown files, whether an inline link, a reference definition, or an
HTML href or src attribute, against the files that Git tracks, so a
target that is untracked or differs in case, which GitHub cannot
serve, fails too. A directory resolves, and its anchors are those of
its README, whatever the README's case. An empty target, such as that
of [Self](), links to its own document.
- It resolves each anchor against the heading slugs that GitHub
generates, including the numeric suffixes of repeated headings, and
against HTML id and name attributes. Other files accept only line
anchors, such as #L10, within their length.
- It scans the blocks of each document as CommonMark nests them in
block quotes and list items, with lazy continuation lines, and strips
their markers before it parses inline content. As on GitHub, front
matter, fenced and indented code, code spans, HTML comments and
blocks, and escaped brackets and tags hold no links, while the
definitions and headings inside block quotes and list items count.
- It parses each reference definition at the start of a paragraph
whole, with its title, before the inline content that follows, and
accepts any destination without spaces, as GitHub does. A reference
link in a heading keeps its brackets in the anchor when no definition
holds its label.
- Links into the openvmm submodule resolve against its pinned commit
when it is checked out and are skipped otherwise, as in the quality
job, whose checkout does not fetch submodules.
- It also resolves, from the repository root, every doc/ path, with any
anchor, that a tracked text file mentions. DOC_PATH_FIXTURES lists
the test fixtures that name missing documents, such as doc/notes.md
in scripts/test_nvx_tools.py, and an entry that its file no longer
needs fails the check. A mention followed by a character that could
extend the path, such as the * of a pattern, is ambiguous and is
skipped.
- It reports each problem with its file and line, as an error
annotation in GitHub Actions, and then exits with status 1.
scripts/test_markdown_links.py covers the slugs, the parsing, the
resolution in temporary repositories, including a submodule, the
fixtures, and the command line, and validate-nvx runs it on Linux and
Windows.
Retarget the README link to native-proxy-and-host-loopback, the only
broken link that the check found, and document the check in
doc/contribute.md, doc/setup.md, and doc/project-structure.md.
Fixes#563
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Nothing in CI checked the repository's relative Markdown links. #529
moved the design documentation, numbered its sections, and retargeted
every inbound link by hand, while an older link had already broken: the
MXC integration table in aci_edge_sandboxes/README.md linked the anchor
native-proxy-and-forwarded-ports of a heading that #512 had renamed to
"Native proxy and host loopback". GitHub opens a page at its top when an
anchor is missing, so such links break silently, and so do comments
that cite a document by path, as the citations of the removed time ABI
specification did (#562).
Add scripts/check_markdown_links.py, a standard-library check, and run
it in check-quality, whose job runs for every pull request that is
ready for review, including the documentation-only ones that are most
likely to break a link:
- It resolves every relative link and image target of the tracked
Markdown files, whether an inline link, a reference definition, or an
HTML href or src attribute, against the files that Git tracks, so a
target that is untracked or differs in case, which GitHub cannot
serve, fails too. A directory resolves, and its anchors are those of
its README, whatever the README's case. An empty target, such as that
of [Self](), links to its own document.
- It resolves each anchor against the heading slugs that GitHub
generates, including the numeric suffixes of repeated headings, and
against HTML id and name attributes. Other files accept only line
anchors, such as #L10, within their length.
- It scans the blocks of each document as CommonMark nests them in
block quotes, list items, and GitHub's footnote definitions, with
lazy continuation lines, and strips their markers before it parses
inline content. As on GitHub, front matter, fenced and indented code,
code spans, HTML comments and blocks, the attributes of raw HTML
tags, link titles, and escaped brackets and tags hold no links, while
the definitions and headings inside those containers count. A
footnote renders, with its fn- and fnref- anchors, only when inline
content cites it.
- It parses each reference definition at the start of a paragraph
whole, within that paragraph, with its title, before the inline
content that follows, and accepts any destination without spaces, as
GitHub does. In heading text, a reference link or image resolves only
when a definition holds its label.
- Links into the openvmm submodule resolve against its pinned commit
when it is checked out and are skipped otherwise, as in the quality
job, whose checkout does not fetch submodules.
- It also resolves, from the repository root, every doc/ path, with any
anchor, that a tracked text file mentions. DOC_PATH_FIXTURES lists
the test fixtures that name missing documents, such as doc/notes.md
in scripts/test_nvx_tools.py, and an entry that its file no longer
needs fails the check. A mention followed by a character that could
extend the path, such as the * of a pattern, is ambiguous and is
skipped.
- It reports each problem with its file and line, as an error
annotation in GitHub Actions, and then exits with status 1.
scripts/test_markdown_links.py covers the slugs, the parsing, the
resolution in temporary repositories, including a submodule, the
fixtures, and the command line, and validate-nvx runs it on Linux and
Windows.
Retarget the README link to native-proxy-and-host-loopback, the only
broken link that the check found, and document the check in
doc/contribute.md, doc/setup.md, and doc/project-structure.md.
Fixes#563
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Nothing in CI checked the repository's relative Markdown links. #529
moved the design documentation, numbered its sections, and retargeted
every inbound link by hand, while an older link had already broken: the
MXC integration table in aci_edge_sandboxes/README.md linked the anchor
native-proxy-and-forwarded-ports of a heading that #512 had renamed to
"Native proxy and host loopback". GitHub opens a page at its top when an
anchor is missing, so such links break silently, and so do comments
that cite a document by path, as the citations of the removed time ABI
specification did (#562).
Add scripts/check_markdown_links.py, a standard-library check, and run
it in check-quality, whose job runs for every pull request that is
ready for review, including the documentation-only ones that are most
likely to break a link:
- It resolves every relative link and image target of the tracked
Markdown files, whether an inline link, a reference definition, or an
HTML href or src attribute, against the files that Git tracks, so a
target that is untracked or differs in case, which GitHub cannot
serve, fails too. A directory resolves, and its anchors are those of
its README, whatever the README's case. An empty target, such as that
of [Self](), links to its own document.
- It resolves each anchor against the heading slugs that GitHub
generates, including the numeric suffixes of repeated headings, and
against HTML id and name attributes. Other files accept only line
anchors, such as #L10, within their length.
- It scans the blocks of each document as CommonMark nests them in
block quotes, list items, and GitHub's footnote definitions, with
lazy continuation lines, and strips their markers before it parses
inline content. As on GitHub, front matter, fenced and indented code,
code spans, HTML comments and blocks, the attributes of raw HTML
tags, link titles, image descriptions, and escaped brackets and tags
hold no links, while the definitions and headings inside those
containers count. A footnote renders, with its fn- and fnref-
anchors, only when inline content cites it.
- It matches brackets as CommonMark does, so links do not nest: an
inner link leaves the brackets around it literal. Each cell of a
table parses alone, and the cells past the header's count, which
GitHub drops, hold no links.
- It parses each reference definition at the start of a paragraph
whole, within that paragraph, with its title, before the inline
content that follows, and accepts any destination without spaces, as
GitHub does. In heading text, a reference link or image resolves only
when a definition holds its label.
- Links into the openvmm submodule resolve against its pinned commit
when it is checked out and are skipped otherwise, as in the quality
job, whose checkout does not fetch submodules.
- It also resolves, from the repository root, every doc/ path, with any
anchor, that a tracked text file mentions. DOC_PATH_FIXTURES lists
the test fixtures that name missing documents, such as doc/notes.md
in scripts/test_nvx_tools.py, and an entry that its file no longer
needs fails the check. A mention followed by a character that could
extend the path, such as the * of a pattern, is ambiguous and is
skipped.
- It reports each problem with its file and line, as an error
annotation in GitHub Actions, and then exits with status 1.
scripts/test_markdown_links.py covers the slugs, the parsing, the
resolution in temporary repositories, including a submodule, the
fixtures, and the command line, and validate-nvx runs it on Linux and
Windows.
Retarget the README link to native-proxy-and-host-loopback, the only
broken link that the check found, and document the check in
doc/contribute.md, doc/setup.md, and doc/project-structure.md.
Fixes#563
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Nothing in CI checked the repository's relative Markdown links. #529
moved the design documentation, numbered its sections, and retargeted
every inbound link by hand, while an older link had already broken: the
MXC integration table in aci_edge_sandboxes/README.md linked the anchor
native-proxy-and-forwarded-ports of a heading that #512 had renamed to
"Native proxy and host loopback". GitHub opens a page at its top when an
anchor is missing, so such links break silently, and so do comments
that cite a document by path, as the citations of the removed time ABI
specification did (#562).
Add scripts/check_markdown_links.py, a standard-library check, and run
it in check-quality, whose job runs for every pull request that is
ready for review, including the documentation-only ones that are most
likely to break a link:
- It resolves every relative link and image target of the tracked
Markdown files, whether an inline link, a reference definition, or an
HTML href or src attribute, against the files that Git tracks, so a
target that is untracked or differs in case, which GitHub cannot
serve, fails too. A directory resolves, and its anchors are those of
its README, whatever the README's case. An empty target, such as that
of [Self](), links to its own document.
- It resolves each anchor against the slugs that GitHub generates from
the rendered text of the headings, including the numeric suffixes of
repeated headings, and against HTML id and name attributes. Other
files accept only line anchors, such as #L10, within their length.
- It scans the blocks of each document as CommonMark nests them in
block quotes, list items, and GitHub's footnote definitions, with
lazy continuation lines, and strips their markers before it parses
inline content. As on GitHub, front matter, fenced and indented code,
and HTML comments and blocks hold no links, while the definitions and
headings inside those containers count.
- It parses inline content left to right as CommonMark does: code
spans, autolinks, and raw HTML are atomic, each destination is
consumed with its title, and brackets match so that links do not nest
and an image's description holds no links. A footnote renders, with
its fn- and fnref- anchors, only where inline content cites it. Each
cell of a table parses alone, and the cells past the header's count,
which GitHub drops, hold no links.
- It parses each reference definition at the start of a paragraph
whole, within that paragraph, with its title, before the inline
content that follows, and accepts any destination without spaces, as
GitHub does. In heading text, a reference link or image resolves only
when a definition holds its label.
- Links into the openvmm submodule resolve against its pinned commit
when it is checked out and are skipped otherwise, as in the quality
job, whose checkout does not fetch submodules.
- It also resolves, from the repository root, every doc/ path, with any
anchor, that a tracked text file mentions. DOC_PATH_FIXTURES lists
the test fixtures that name missing documents, such as doc/notes.md
in scripts/test_nvx_tools.py, and an entry that its file no longer
needs fails the check. A mention followed by a character that could
extend the path, such as the * of a pattern, is ambiguous and is
skipped.
- It reports each problem with its file and line, as an error
annotation in GitHub Actions, and then exits with status 1.
scripts/test_markdown_links.py covers the slugs, the parsing, the
resolution in temporary repositories, including a submodule, the
fixtures, and the command line, and validate-nvx runs it on Linux and
Windows.
Retarget the README link to native-proxy-and-host-loopback, the only
broken link that the check found, and document the check in
doc/contribute.md, doc/setup.md, and doc/project-structure.md.
Fixes#563
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Nothing in CI checked the repository's relative Markdown links. #529
moved the design documentation, numbered its sections, and retargeted
every inbound link by hand, while an older link had already broken: the
MXC integration table in aci_edge_sandboxes/README.md linked the anchor
native-proxy-and-forwarded-ports of a heading that #512 had renamed to
"Native proxy and host loopback". GitHub opens a page at its top when an
anchor is missing, so such links break silently, and so do comments
that cite a document by path, as the citations of the removed time ABI
specification did (#562).
Add scripts/check_markdown_links.py, a standard-library check, and run
it in check-quality, whose job runs for every pull request that is
ready for review, including the documentation-only ones that are most
likely to break a link:
- It resolves every relative link and image target of the tracked
Markdown files, whether an inline link, a reference definition, or an
HTML href or src attribute, against the files that Git tracks, so a
target that is untracked or differs in case, which GitHub cannot
serve, fails too. A directory resolves, and its anchors are those of
its README, whatever the README's case. An empty target, such as that
of [Self](), links to its own document.
- It resolves each anchor against the slugs that GitHub generates from
the rendered text of the headings, including the numeric suffixes of
repeated headings, and against HTML id and name attributes. Other
files accept only line anchors, such as #L10, within their length.
- It scans the blocks of each document as cmark nests them in block
quotes, list items, and GitHub's footnote definitions, with lazy
continuation lines and tabs that advance to the next multiple of four
columns, and strips their markers before it parses inline content. As
on GitHub, front matter, fenced and indented code, and the seven kinds
of HTML blocks hold no Markdown links, while the definitions and
headings inside those containers count.
- It parses inline content left to right as CommonMark does: code
spans, autolinks, and raw HTML are atomic, each destination is
consumed with its title, and brackets match so that links do not nest
and an image's description holds no links. A footnote renders, with
its fn- and fnref- anchors, only where inline content cites it. Each
cell of a table parses alone, and the cells past the header's count,
which GitHub drops, hold no links.
- It tokenizes the raw HTML, in the order that GitHub renders it, as an
HTML parser does, to find the tags whose attributes hold targets and
anchors. A comment hides everything that renders up to its end, even
in later blocks, while a CDATA section, processing instruction, or
declaration ends at its first >.
- It parses each reference definition at the start of a paragraph
whole, within that paragraph, with its title, before the inline
content that follows, and accepts any destination without spaces, as
GitHub does. In heading text, a reference link or image resolves only
when a definition holds its label.
- It decodes a destination as cmark does, its character references
before its backslash escapes, and an HTML attribute as GitHub does,
which keeps its backslashes, and its named references without
semicolons, literal.
- Links into the openvmm submodule resolve against its pinned commit
when it is checked out and are skipped otherwise, as in the quality
job, whose checkout does not fetch submodules.
- It also resolves, from the repository root, every doc/ path, with any
anchor, that a tracked text file mentions. DOC_PATH_FIXTURES lists
the test fixtures that name missing documents, such as doc/notes.md
in scripts/test_nvx_tools.py, and an entry that its file no longer
needs fails the check. A mention followed by a character that could
extend the path, such as the * of a pattern, is ambiguous and is
skipped.
- It reports each problem with its file and line, as an error
annotation in GitHub Actions, and then exits with status 1.
scripts/test_markdown_links.py covers the slugs, the parsing, the
resolution in temporary repositories, including a submodule, the
fixtures, and the command line, and validate-nvx runs it on Linux and
Windows.
Retarget the README link to native-proxy-and-host-loopback, the only
broken link that the check found, and document the check in
doc/contribute.md, doc/setup.md, and doc/project-structure.md.
Fixes#563
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Nothing in CI checked the repository's relative Markdown links. #529
moved the design documentation, numbered its sections, and retargeted
every inbound link by hand, while an older link had already broken: the
MXC integration table in aci_edge_sandboxes/README.md linked the anchor
native-proxy-and-forwarded-ports of a heading that #512 had renamed to
"Native proxy and host loopback". GitHub opens a page at its top when an
anchor is missing, so such links break silently, and so do comments
that cite a document by path, as the citations of the removed time ABI
specification did (#562).
Add scripts/check_markdown_links.py, a standard-library check, and run
it in check-quality, whose job runs for every pull request that is
ready for review, including the documentation-only ones that are most
likely to break a link:
- It resolves every relative link and image target of the tracked
Markdown files, whether an inline link, a reference definition, or
the href of an HTML link or src of an image, against the files that
Git tracks, so a target that is untracked or differs in case, which
GitHub cannot serve, fails too. A directory resolves, and its anchors
are those of its README, whatever the README's case. An empty target,
such as that of [Self](), links to its own document.
- It resolves each anchor against the slugs that GitHub generates from
the rendered text of the Markdown and HTML headings, including the
numeric suffixes of repeated headings, and against the id and name
attributes of the HTML elements that GitHub keeps. Other files accept
only line anchors, such as #L10, within their length.
- It scans the blocks of each document as cmark nests them in block
quotes, list items, and GitHub's footnote definitions, with lazy
continuation lines and tabs that advance to the next multiple of four
columns, and strips their markers before it parses inline content. As
on GitHub, front matter, fenced and indented code, and the seven kinds
of HTML blocks hold no Markdown links, while the definitions and
headings inside those containers count.
- It parses inline content left to right as CommonMark does: code
spans, autolinks, and raw HTML are atomic, each destination is
consumed with its title, and brackets match so that links do not nest
and an image's description holds no links. A footnote renders, with
its fn- and fnref- anchors, only where inline content cites it. Each
cell of a table parses alone, and the cells past the header's count,
which GitHub drops, hold no links.
- It tokenizes the raw HTML, in the order that GitHub renders it, as an
HTML parser does, to find the tags whose attributes hold targets and
anchors. A comment hides everything that renders up to its end, even
in later blocks, while a CDATA section, processing instruction, or
declaration ends at its first >. The tags that GitHub filters, such
as <script> and <iframe>, render as text.
- It parses each reference definition at the start of a paragraph
whole, within that paragraph, with its title, before the inline
content that follows, and accepts any destination without spaces, as
GitHub does. In heading text, a reference link or image resolves only
when a definition holds its label.
- It decodes a destination as cmark does, its character references
before its backslash escapes, and an HTML attribute as GitHub does,
which keeps its backslashes, and its named references without
semicolons, literal.
- Links into the openvmm submodule resolve against its pinned commit
when it is checked out and are skipped otherwise, as in the quality
job, whose checkout does not fetch submodules.
- It also resolves, from the repository root, every doc/ path, with any
anchor, that a tracked text file mentions. DOC_PATH_FIXTURES lists
the test fixtures that name missing documents, such as doc/notes.md
in scripts/test_nvx_tools.py, and an entry that its file no longer
needs fails the check. A mention followed by a character that could
extend the path, such as the * of a pattern, is ambiguous and is
skipped.
- It reports each problem with its file and line, as an error
annotation in GitHub Actions, and then exits with status 1.
scripts/test_markdown_links.py covers the slugs, the parsing, the
resolution in temporary repositories, including a submodule, the
fixtures, and the command line, and validate-nvx runs it on Linux and
Windows.
Retarget the README link to native-proxy-and-host-loopback, the only
broken link that the check found, and document the check in
doc/contribute.md, doc/setup.md, and doc/project-structure.md.
Fixes#563
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Nothing in CI checked the repository's relative Markdown links. #529
moved the design documentation, numbered its sections, and retargeted
every inbound link by hand, while an older link had already broken: the
MXC integration table in aci_edge_sandboxes/README.md linked the anchor
native-proxy-and-forwarded-ports of a heading that #512 had renamed to
"Native proxy and host loopback". GitHub opens a page at its top when an
anchor is missing, so such links break silently, and so do comments
that cite a document by path, as the citations of the removed time ABI
specification did (#562).
Add scripts/check_markdown_links.py, a standard-library check, and run
it in check-quality, whose job runs for every pull request that is
ready for review, including the documentation-only ones that are most
likely to break a link:
- It resolves every relative link and image target of the tracked
Markdown files, whether an inline link, a reference definition, or
the href of an HTML link or src of an image, against the files that
Git tracks, so a target that is untracked or differs in case, which
GitHub cannot serve, fails too. A directory resolves, and its anchors
are those of its README, whatever the README's case. An empty target,
such as that of [Self](), links to its own document.
- It resolves each anchor against the slugs that GitHub generates from
the rendered text of the Markdown and HTML headings, including the
numeric suffixes of repeated headings, and against the id and name
attributes of the HTML elements that GitHub keeps. Other files accept
only line anchors, such as #L10, within their length.
- It scans the blocks of each document as cmark nests them in block
quotes, list items, and GitHub's footnote definitions, with lazy
continuation lines and tabs that advance to the next multiple of four
columns, and strips their markers before it parses inline content. As
on GitHub, front matter, fenced and indented code, and the seven kinds
of HTML blocks hold no Markdown links, while the definitions and
headings inside those containers count.
- It parses inline content left to right as CommonMark does: code
spans, autolinks, and raw HTML are atomic, each destination is
consumed with its title, and brackets match so that links do not nest
and an image's description holds no links. A footnote renders, with
its fn- and fnref- anchors, only where inline content cites it. Each
cell of a table parses alone, and the cells past the header's count,
which GitHub drops, hold no links.
- It tokenizes the raw HTML, in the order that GitHub renders it, as an
HTML parser does, to find the tags whose attributes hold targets and
anchors. A comment hides everything that renders up to its end, even
in later blocks, while a CDATA section, processing instruction, or
declaration ends at its first >. The tags that GitHub filters, such
as <script> and <iframe>, render as text.
- It parses each reference definition at the start of a paragraph
whole, within that paragraph, with its title, before the inline
content that follows, and accepts any destination without spaces, as
GitHub does. In heading text, a reference link or image resolves only
when a definition holds its label, and the delimiters of emphasis and
strikethrough match as cmark-gfm matches them, those of each link's
text alone.
- It decodes a destination as cmark does, its character references
before its backslash escapes, and an HTML attribute as GitHub does,
which keeps its backslashes, and its named references without
semicolons, literal.
- Links into the openvmm submodule resolve against its pinned commit
when it is checked out and are skipped otherwise, as in the quality
job, whose checkout does not fetch submodules.
- It also resolves, from the repository root, every doc/ path, with any
anchor, that a tracked text file mentions. DOC_PATH_FIXTURES lists
the test fixtures that name missing documents, such as doc/notes.md
in scripts/test_nvx_tools.py, and an entry that its file no longer
needs fails the check. A mention followed by a character that could
extend the path, such as the * of a pattern, is ambiguous and is
skipped.
- It reports each problem with its file and line, as an error
annotation in GitHub Actions, and then exits with status 1.
scripts/test_markdown_links.py covers the slugs, the parsing, the
resolution in temporary repositories, including a submodule, the
fixtures, and the command line, and validate-nvx runs it on Linux and
Windows.
Retarget the README link to native-proxy-and-host-loopback, the only
broken link that the check found, and document the check in
doc/contribute.md, doc/setup.md, and doc/project-structure.md.
Fixes#563
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Nothing in CI checked the repository's relative Markdown links. #529
moved the design documentation, numbered its sections, and retargeted
every inbound link by hand, while an older link had already broken: the
MXC integration table in aci_edge_sandboxes/README.md linked the anchor
native-proxy-and-forwarded-ports of a heading that #512 had renamed to
"Native proxy and host loopback". GitHub opens a page at its top when an
anchor is missing, so such links break silently, and so do comments
that cite a document by path, as the citations of the removed time ABI
specification did (#562).
Add scripts/check_markdown_links.py, a standard-library check, and run
it in check-quality, whose job runs for every pull request that is
ready for review, including the documentation-only ones that are most
likely to break a link:
- It resolves every relative link and image target of the tracked
Markdown files, whether an inline link, a reference definition, or
the href of an HTML link or src of an image, against the files that
Git tracks, so a target that is untracked or differs in case, which
GitHub cannot serve, fails too. A directory resolves, and its anchors
are those of its README, whatever the README's case. An empty target,
such as that of [Self](), links to its own document, and an image's
anchor, such as GitHub's #gh-dark-mode-only, goes unchecked.
- It resolves each anchor against the slugs that GitHub generates from
the rendered text of the Markdown and HTML headings, including the
numeric suffixes of repeated headings, and against the id and name
attributes of the HTML elements that GitHub keeps. Other files accept
only line anchors, such as #L10, within their length.
- It scans the blocks of each document as cmark nests them in block
quotes, list items, and GitHub's footnote definitions, with lazy
continuation lines and tabs that advance to the next multiple of four
columns, and strips their markers before it parses inline content. As
on GitHub, front matter, fenced and indented code, and the seven kinds
of HTML blocks hold no Markdown links, while the definitions and
headings inside those containers count.
- It parses inline content left to right as CommonMark does: code
spans, autolinks, and raw HTML are atomic, each destination is
consumed with its title, and brackets match so that links do not nest
and an image's description holds no links. A footnote renders, with
its fn- and fnref- anchors, only where inline content cites it. A
table is a block of its own, which ends as GitHub's table extension
ends it, and each of its cells parses alone, while the cells past the
header's count, which GitHub drops, hold no links.
- It tokenizes the raw HTML, in the order that GitHub renders it, as an
HTML parser does, to find the tags whose attributes hold targets and
anchors. A comment hides everything that renders up to its end, even
in later blocks, while a CDATA section, processing instruction, or
declaration ends at its first >. The tags that GitHub filters, such
as <script> and <iframe>, render as text.
- It parses each reference definition at the start of a paragraph
whole, within that paragraph, with its title, before the inline
content that follows, and accepts any destination without spaces, as
GitHub does. In heading text, a reference link or image resolves only
when a definition holds its label, and the delimiters of emphasis and
strikethrough match as cmark-gfm matches them, those of each link's
text alone.
- It decodes a destination as cmark does, its character references
before its backslash escapes, and an HTML attribute as GitHub does,
which keeps its backslashes, and its named references without
semicolons, literal.
- Links into the openvmm submodule resolve against its pinned commit
when it is checked out and are skipped otherwise, as in the quality
job, whose checkout does not fetch submodules.
- It also resolves, from the repository root, every doc/ path, with any
anchor, that a tracked text file mentions. DOC_PATH_FIXTURES lists
the test fixtures that name missing documents, such as doc/notes.md
in scripts/test_nvx_tools.py, and an entry that its file no longer
needs fails the check. A mention followed by a character that could
extend the path, such as the * of a pattern, is ambiguous and is
skipped.
- It reports each problem with its file and line, as an error
annotation in GitHub Actions, and then exits with status 1.
scripts/test_markdown_links.py covers the slugs, the parsing, the
resolution in temporary repositories, including a submodule, the
fixtures, and the command line, and validate-nvx runs it on Linux and
Windows.
Retarget the README link to native-proxy-and-host-loopback, the only
broken link that the check found, and document the check in
doc/contribute.md, doc/setup.md, and doc/project-structure.md.
Fixes#563
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Nothing in CI checked the repository's relative Markdown links. #529
moved the design documentation, numbered its sections, and retargeted
every inbound link by hand, while an older link had already broken: the
MXC integration table in aci_edge_sandboxes/README.md linked the anchor
native-proxy-and-forwarded-ports of a heading that #512 had renamed to
"Native proxy and host loopback". GitHub opens a page at its top when an
anchor is missing, so such links break silently, and so do comments
that cite a document by path, as the citations of the removed time ABI
specification did (#562).
Add scripts/check_markdown_links.py, a standard-library check, and run
it in check-quality, whose job runs for every pull request that is
ready for review, including the documentation-only ones that are most
likely to break a link:
- It resolves every relative link and image target of the tracked
Markdown files, whether an inline link, a reference definition, or
the href of an HTML link or src of an image, against the files that
Git tracks, so a target that is untracked or differs in case, which
GitHub cannot serve, fails too. A directory resolves, and its anchors
are those of its README, whatever the README's case. An empty target,
such as that of [Self](), links to its own document, and an image's
anchor, such as GitHub's #gh-dark-mode-only, goes unchecked.
- It resolves each anchor against the slugs that GitHub generates from
the rendered text of the Markdown and HTML headings, including the
numeric suffixes of repeated headings, and against the id and name
attributes of the HTML elements that GitHub keeps. Other files accept
only line anchors, such as #L10, within their length.
- It scans the blocks of each document as cmark nests them in block
quotes, list items, and GitHub's footnote definitions, with lazy
continuation lines and tabs that advance to the next multiple of four
columns, and strips their markers before it parses inline content. As
on GitHub, front matter, fenced and indented code, and the seven kinds
of HTML blocks hold no Markdown links, while the definitions and
headings inside those containers count.
- It parses inline content left to right as CommonMark does: code
spans, autolinks, and raw HTML are atomic, each destination is
consumed with its title, and brackets match so that links do not nest
and an image's description holds no links. A footnote renders, with
its fn- and fnref- anchors, only where inline content cites it. A
table is a block of its own, which ends as GitHub's table extension
ends it, and each of its cells parses alone, while the cells past the
header's count, which GitHub drops, hold no links.
- It tokenizes the raw HTML, in the order that GitHub renders it, as an
HTML parser does, to find the tags whose attributes hold targets and
anchors. A comment hides everything that renders up to its end, even
in later blocks, while a CDATA section, processing instruction, or
declaration ends at its first >. The tags that GitHub filters, such
as <script> and <iframe>, render as text.
- It parses each reference definition at the start of a paragraph
whole, within that paragraph, with its title, before the inline
content that follows, and accepts any destination without spaces, as
GitHub does. In heading text, a reference link or image resolves only
when a definition holds its label, and the delimiters of emphasis and
strikethrough match as cmark-gfm matches them, those of each link's
text alone.
- It decodes a destination as cmark does, its character references
before its backslash escapes, and an HTML attribute as GitHub does,
which keeps its backslashes, and its named references without
semicolons, literal.
- Links into the openvmm submodule resolve against its pinned commit
when it is checked out and are skipped otherwise, as in the quality
job, whose checkout does not fetch submodules.
- It also resolves, from the repository root, every doc/ path, with any
anchor, that a tracked text file mentions. DOC_PATH_FIXTURES lists
the test fixtures that name missing documents, such as doc/notes.md
in scripts/test_nvx_tools.py, and an entry that its file no longer
needs fails the check. A mention followed by a character that could
extend the path, such as the * of a pattern, is ambiguous and is
skipped.
- It reports each problem with its file and line, as an error
annotation in GitHub Actions, and then exits with status 1.
scripts/test_markdown_links.py covers the slugs, the parsing, the
resolution in temporary repositories, including a submodule, the
fixtures, and the command line, and validate-nvx runs it on Linux and
Windows.
Retarget the README link to native-proxy-and-host-loopback, the only
broken link that the check found, and document the check in
doc/contribute.md, doc/setup.md, and doc/project-structure.md.
Fixes#563
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Nothing in CI checked the repository's relative Markdown links. #529
moved the design documentation, numbered its sections, and retargeted
every inbound link by hand, while an older link had already broken: the
MXC integration table in aci_edge_sandboxes/README.md linked the anchor
native-proxy-and-forwarded-ports of a heading that #512 had renamed to
"Native proxy and host loopback". GitHub opens a page at its top when an
anchor is missing, so such links break silently, and so do comments
that cite a document by path, as the citations of the removed time ABI
specification did (#562).
Add scripts/check_markdown_links.py, a standard-library check, and run
it in check-quality, whose job runs for every pull request that is
ready for review, including the documentation-only ones that are most
likely to break a link:
- It resolves every relative link and image target of the tracked
Markdown files, whether an inline link, a reference definition, or
the href of an HTML link or src of an image, against the files that
Git tracks, so a target that is untracked or differs in case, which
GitHub cannot serve, fails too. A directory resolves, and its anchors
are those of its README, whatever the README's case. An empty target,
such as that of [Self](), links to its own document, and an image's
anchor, such as GitHub's #gh-dark-mode-only, goes unchecked.
- It resolves each anchor, in lowercase as GitHub's script looks it up,
against the slugs that GitHub generates from the rendered text of the
Markdown and HTML headings, including the numeric suffixes of repeated
headings, and against the id and name attributes of the HTML elements
that GitHub keeps. Other files accept only line anchors, such as #L10,
within their length.
- It scans the blocks of each document as cmark nests them in block
quotes, list items, and GitHub's footnote definitions, with lazy
continuation lines and tabs that advance to the next multiple of four
columns, and strips their markers before it parses inline content. As
on GitHub, front matter, fenced and indented code, and the seven kinds
of HTML blocks hold no Markdown links, while the definitions and
headings inside those containers count.
- It parses inline content left to right as CommonMark does: code spans,
autolinks, including GitHub's bare ones, and raw HTML are atomic, each
destination is consumed with its title, and brackets match so that
links do not nest and an image's description holds no links. A
footnote renders, with its fn- and fnref- anchors, only where inline
content cites it. A table is a block of its own, which ends as
GitHub's table extension ends it, and each of its cells parses alone,
while the cells past the header's count, which GitHub drops, hold no
links.
- It tokenizes the raw HTML, in the order that GitHub renders it, as an
HTML parser does, to find the tags whose attributes hold targets and
anchors. A comment hides everything that renders up to its end, even
in later blocks, while a CDATA section, processing instruction, or
declaration ends at its first >. The tags that GitHub filters, such
as <script> and <iframe>, render as text.
- It parses each reference definition at the start of a paragraph
whole, within that paragraph, with its title, before the inline
content that follows, and accepts any destination without spaces, as
GitHub does. In heading text, a reference link or image resolves only
when a definition holds its label, a citation renders as its
footnote's number, and the delimiters of emphasis and strikethrough
match as cmark-gfm matches them, those of each link's text alone.
- It decodes a destination as cmark does, its character references
before its backslash escapes, and an HTML attribute as GitHub does,
which keeps its backslashes, and its named references without
semicolons, literal.
- Links into the openvmm submodule resolve against its pinned commit
when it is checked out and are skipped otherwise, as in the quality
job, whose checkout does not fetch submodules.
- It also resolves, from the repository root, every doc/ path, with any
anchor, that a tracked text file mentions. DOC_PATH_FIXTURES lists
the test fixtures that name missing documents, such as doc/notes.md
in scripts/test_nvx_tools.py, and an entry that its file no longer
needs fails the check. A mention followed by a character that could
extend the path, such as the * of a pattern, is ambiguous and is
skipped.
- It reports each problem with its file and line, as an error
annotation in GitHub Actions, and then exits with status 1.
scripts/test_markdown_links.py covers the slugs, the parsing, the
resolution in temporary repositories, including a submodule, the
fixtures, and the command line, and validate-nvx runs it on Linux and
Windows.
Retarget the README link to native-proxy-and-host-loopback, the only
broken link that the check found, and document the check in
doc/contribute.md, doc/setup.md, and doc/project-structure.md.
Fixes#563
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Nothing in CI checked the repository's relative Markdown links. #529
moved the design documentation, numbered its sections, and retargeted
every inbound link by hand, while an older link had already broken: the
MXC integration table in aci_edge_sandboxes/README.md linked the anchor
native-proxy-and-forwarded-ports of a heading that #512 had renamed to
"Native proxy and host loopback". GitHub opens a page at its top when an
anchor is missing, so such links break silently, and so do comments
that cite a document by path, as the citations of the removed time ABI
specification did (#562).
Add scripts/check_markdown_links.py, a standard-library check, and run
it in check-quality, whose job runs for every pull request that is
ready for review, including the documentation-only ones that are most
likely to break a link:
- It resolves every relative link and image target of the tracked
Markdown files, whether an inline link, a reference definition, or
the href of an HTML link or src of an image, against the files that
Git tracks, so a target that is untracked or differs in case, which
GitHub cannot serve, fails too. A directory resolves, and its anchors
are those of its README, whatever the README's case. An empty target,
such as that of [Self](), links to its own document, and an image's
anchor, such as GitHub's #gh-dark-mode-only, goes unchecked.
- It resolves each anchor, in lowercase as GitHub's script looks it up,
against the slugs that GitHub generates from the rendered text of the
Markdown and HTML headings, including the numeric suffixes of repeated
headings, and against the id and name attributes of the HTML elements
that GitHub keeps. Other files accept only line anchors, such as #L10,
within their length.
- It scans the blocks of each document as cmark nests them in block
quotes, list items, and GitHub's footnote definitions, with lazy
continuation lines and tabs that advance to the next multiple of four
columns, and strips their markers before it parses inline content. As
on GitHub, front matter, fenced and indented code, and the seven kinds
of HTML blocks hold no Markdown links, while the definitions and
headings inside those containers count.
- It parses inline content left to right as CommonMark does: code spans,
autolinks, including GitHub's bare ones, and raw HTML are atomic, each
destination is consumed with its title, and brackets match so that
links do not nest and an image's description holds no links. A
footnote renders, with its fn- and fnref- anchors, only where inline
content cites it. A table is a block of its own, which ends as
GitHub's table extension ends it, and each of its cells parses alone,
while the cells past the header's count, which GitHub drops, hold no
links.
- It tokenizes the raw HTML, in the order that GitHub renders it, as an
HTML parser does, to find the tags whose attributes hold targets and
anchors. A comment hides everything that renders up to its end, even
in later blocks, while a CDATA section, processing instruction, or
declaration ends at its first >. The tags that GitHub filters, such
as <script> and <iframe>, render as text.
- It parses each reference definition at the start of a paragraph
whole, within that paragraph, with its title, before the inline
content that follows, and accepts any destination without spaces, as
GitHub does. In heading text, a reference link or image resolves only
when a definition holds its label, a citation renders as its
footnote's number, and the delimiters of emphasis and strikethrough
match as cmark-gfm matches them, those of each link's text alone.
- It decodes a destination as cmark does, trimmed and with its
character references before its backslash escapes, and an HTML
attribute as GitHub does, which keeps its backslashes, and its named
references without semicolons, literal, and drops only the leading
whitespace of a URL. As in HTML, the first attribute of each name
hides the others.
- Links into the openvmm submodule resolve against its pinned commit
when it is checked out and are skipped otherwise, as in the quality
job, whose checkout does not fetch submodules.
- It also resolves, from the repository root, every doc/ path, with any
anchor, that a tracked text file mentions. DOC_PATH_FIXTURES lists
the test fixtures that name missing documents, such as doc/notes.md
in scripts/test_nvx_tools.py, and an entry that its file no longer
needs fails the check. A mention followed by a character that could
extend the path, such as the * of a pattern, is ambiguous and is
skipped.
- It reports each problem with its file and line, as an error
annotation in GitHub Actions, and then exits with status 1.
scripts/test_markdown_links.py covers the slugs, the parsing, the
resolution in temporary repositories, including a submodule, the
fixtures, and the command line, and validate-nvx runs it on Linux and
Windows.
Retarget the README link to native-proxy-and-host-loopback, the only
broken link that the check found, and document the check in
doc/contribute.md, doc/setup.md, and doc/project-structure.md.
Fixes#563
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Nothing in CI checked the repository's relative Markdown links. #529
moved the design documentation, numbered its sections, and retargeted
every inbound link by hand, while an older link had already broken: the
MXC integration table in aci_edge_sandboxes/README.md linked the anchor
native-proxy-and-forwarded-ports of a heading that #512 had renamed to
"Native proxy and host loopback". GitHub opens a page at its top when an
anchor is missing, so such links break silently, and so do comments
that cite a document by path, as the citations of the removed time ABI
specification did (#562).
Add scripts/check_markdown_links.py, a standard-library check, and run
it in check-quality, whose job runs for every pull request that is
ready for review, including the documentation-only ones that are most
likely to break a link:
- It resolves every relative link and image target of the tracked
Markdown files, whether an inline link, a reference definition, or
the href of an HTML link or src of an image, against the files that
Git tracks, so a target that is untracked or differs in case, which
GitHub cannot serve, fails too. A directory resolves, and its anchors
are those of its README, whatever the README's case. An empty target,
such as that of [Self](), links to its own document, and an image's
anchor, such as GitHub's #gh-dark-mode-only, goes unchecked.
- It resolves each anchor as GitHub's script looks it up, in lowercase
and with the user-content- prefix of the ids that GitHub renders,
which the anchor may hold already, against the slugs that GitHub
generates from the rendered text of the Markdown and HTML headings,
including the numeric suffixes of repeated headings, and against the
id and name attributes of the HTML elements that GitHub keeps. Other
files accept only line anchors, such as #L10, within their length.
- It scans the blocks of each document as cmark nests them in block
quotes, list items, and GitHub's footnote definitions, with lazy
continuation lines and tabs that advance to the next multiple of four
columns, and strips their markers before it parses inline content. As
on GitHub, front matter, fenced and indented code, and the seven kinds
of HTML blocks hold no Markdown links, while the definitions and
headings inside those containers count.
- It parses inline content left to right as CommonMark does: code spans,
autolinks, including GitHub's bare ones, and raw HTML are atomic, each
destination is consumed with its title, and brackets match so that
links do not nest and an image's description holds no links. A
footnote renders, with its fn- and fnref- anchors, only where inline
content cites it. A table is a block of its own, which ends as
GitHub's table extension ends it, and each of its cells parses alone,
while the cells past the header's count, which GitHub drops, hold no
links.
- It tokenizes the raw HTML, in the order that GitHub renders it, as an
HTML parser does, to find the tags whose attributes hold targets and
anchors. A comment hides everything that renders up to its end, even
in later blocks, while a CDATA section, processing instruction, or
declaration ends at its first >. The tags that GitHub filters, such
as <script> and <iframe>, render as text.
- It parses each reference definition at the start of a paragraph
whole, within that paragraph, with its title, before the inline
content that follows, and accepts any destination without spaces, as
GitHub does. In heading text, a reference link or image resolves only
when a definition holds its label, a citation renders as its
footnote's number, and the delimiters of emphasis and strikethrough
match as cmark-gfm matches them, those of each link's text alone.
- It decodes a destination as cmark does, trimmed and with its
character references before its backslash escapes, and an HTML
attribute as GitHub does, which keeps its backslashes, and its named
references without semicolons, literal, and drops only the leading
whitespace of a URL. As in HTML, the first attribute of each name
hides the others.
- Links into the openvmm submodule resolve against its pinned commit
when it is checked out and are skipped otherwise, as in the quality
job, whose checkout does not fetch submodules.
- It also resolves, from the repository root, every doc/ path, with any
anchor, that a tracked text file mentions. DOC_PATH_FIXTURES lists
the test fixtures that name missing documents, such as doc/notes.md
in scripts/test_nvx_tools.py, and an entry that its file no longer
needs fails the check. A mention followed by a character that could
extend the path, such as the * of a pattern, is ambiguous and is
skipped.
- It reports each problem with its file and line, as an error
annotation in GitHub Actions, and then exits with status 1.
scripts/test_markdown_links.py covers the slugs, the parsing, the
resolution in temporary repositories, including a submodule, the
fixtures, and the command line, and validate-nvx runs it on Linux and
Windows.
Retarget the README link to native-proxy-and-host-loopback, the only
broken link that the check found, and document the check in
doc/contribute.md, doc/setup.md, and doc/project-structure.md.
Fixes#563
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Nothing in CI checked the repository's relative Markdown links. #529
moved the design documentation, numbered its sections, and retargeted
every inbound link by hand, while an older link had already broken: the
MXC integration table in aci_edge_sandboxes/README.md linked the anchor
native-proxy-and-forwarded-ports of a heading that #512 had renamed to
"Native proxy and host loopback". GitHub opens a page at its top when an
anchor is missing, so such links break silently, and so do comments
that cite a document by path, as the citations of the removed time ABI
specification did (#562).
Add scripts/check_markdown_links.py, a standard-library check, and run
it in check-quality, whose job runs for every pull request that is
ready for review, including the documentation-only ones that are most
likely to break a link:
- It resolves every relative link and image target of the tracked
Markdown files, whether an inline link, a reference definition, or
the href of an HTML link or src of an image, against the files that
Git tracks, so a target that is untracked or differs in case, which
GitHub cannot serve, fails too. A directory resolves, and its anchors
are those of its README, whatever the README's case. An empty target,
such as that of [Self](), links to its own document, and an image's
anchor, such as GitHub's #gh-dark-mode-only, goes unchecked.
- It resolves each anchor as GitHub's script looks it up, in lowercase
and with the user-content- prefix of the ids that GitHub renders,
which the anchor may hold already, against the slugs that GitHub
generates from the rendered text of the Markdown and HTML headings,
including the numeric suffixes of repeated headings, and against the
id and name attributes of the HTML elements that GitHub keeps. Other
files accept only line anchors, such as #L10, within their length.
- It scans the blocks of each document as cmark nests them in block
quotes, list items, and GitHub's footnote definitions, with lazy
continuation lines and tabs that advance to the next multiple of four
columns, and strips their markers before it parses inline content. As
on GitHub, front matter, fenced and indented code, and the seven kinds
of HTML blocks hold no Markdown links, while the definitions and
headings inside those containers count.
- It parses inline content left to right as CommonMark does: code spans,
autolinks, including GitHub's bare ones, and raw HTML are atomic, each
destination is consumed with its title, and brackets match so that
links do not nest and an image's description holds no links. A
footnote renders, with its fn- and fnref- anchors, only where inline
content cites it. A table is a block of its own, which ends as
GitHub's table extension ends it, and each of its cells parses alone,
while the cells past the header's count, which GitHub drops, hold no
links.
- It tokenizes the raw HTML, in the order that GitHub renders it, as an
HTML parser does, to find the tags whose attributes hold targets and
anchors. A comment hides everything that renders up to its end, even
in later blocks, while a CDATA section, processing instruction, or
declaration ends at its first >. The tags that GitHub filters, such
as <script> and <iframe>, render as text.
- It parses each reference definition at the start of a paragraph whole,
within that paragraph, with its title, before the inline content that
follows, and accepts any destination without spaces, as GitHub does. A
definition counts where it renders, and wherever a rendered reference
uses it, even in a footnote that does not render. In heading text, a
reference link or image resolves only when a definition holds its
label, a citation renders as its footnote's number, and the delimiters
of emphasis and strikethrough match as cmark-gfm matches them, those
of each link's text alone.
- It decodes a destination as cmark does, trimmed and with its
character references before its backslash escapes, and an HTML
attribute as GitHub does, which keeps its backslashes, and its named
references without semicolons, literal, and drops only the leading
whitespace of a URL. As in HTML, the first attribute of each name
hides the others.
- Links into the openvmm submodule resolve against its pinned commit
when it is checked out and are skipped otherwise, as in the quality
job, whose checkout does not fetch submodules.
- It also resolves, from the repository root, every doc/ path, with any
anchor, that a tracked text file mentions. DOC_PATH_FIXTURES lists
the test fixtures that name missing documents, such as doc/notes.md
in scripts/test_nvx_tools.py, and an entry that its file no longer
needs fails the check. A mention followed by a character that could
extend the path, such as the * of a pattern, is ambiguous and is
skipped.
- It reports each problem with its file and line, as an error
annotation in GitHub Actions, and then exits with status 1.
scripts/test_markdown_links.py covers the slugs, the parsing, the
resolution in temporary repositories, including a submodule, the
fixtures, and the command line, and validate-nvx runs it on Linux and
Windows.
Retarget the README link to native-proxy-and-host-loopback, the only
broken link that the check found, and document the check in
doc/contribute.md, doc/setup.md, and doc/project-structure.md.
Fixes#563
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Nothing in CI checked the repository's relative Markdown links. #529
moved the design documentation, numbered its sections, and retargeted
every inbound link by hand, while an older link had already broken: the
MXC integration table in aci_edge_sandboxes/README.md linked the anchor
native-proxy-and-forwarded-ports of a heading that #512 had renamed to
"Native proxy and host loopback". GitHub opens a page at its top when an
anchor is missing, so such links break silently, and so do comments
that cite a document by path, as the citations of the removed time ABI
specification did (#562).
Add scripts/check_markdown_links.py, a standard-library check, and run
it in check-quality, whose job runs for every pull request that is
ready for review, including the documentation-only ones that are most
likely to break a link:
- It resolves every relative link and image target of the tracked
Markdown files, whether an inline link, a reference definition, or
the href of an HTML link or src of an image, against the files that
Git tracks, so a target that is untracked or differs in case, which
GitHub cannot serve, fails too. A directory resolves, and its anchors
are those of its README, whatever the README's case. An empty target,
such as that of [Self](), links to its own document, and an image's
anchor, such as GitHub's #gh-dark-mode-only, goes unchecked.
- It resolves each anchor as GitHub's script looks it up, in lowercase
and with the user-content- prefix of the ids that GitHub renders,
which the anchor may hold already, against the slugs that GitHub
generates from the rendered text of the Markdown and HTML headings,
including the numeric suffixes of repeated headings, and against the
id and name attributes of the HTML elements that GitHub keeps. Other
files accept only line anchors, such as #L10, within their length.
- It scans the blocks of each document as cmark nests them in block
quotes, list items, and GitHub's footnote definitions, with lazy
continuation lines and tabs that advance to the next multiple of four
columns, and strips their markers before it parses inline content. As
on GitHub, front matter, fenced and indented code, and the seven kinds
of HTML blocks hold no Markdown links, while the definitions and
headings inside those containers count.
- It parses inline content left to right as CommonMark does: code spans,
autolinks, including GitHub's bare ones, and raw HTML are atomic, each
destination is consumed with its title, and brackets match so that
links do not nest and an image's description holds no links. A
footnote renders, with its fn- and fnref- anchors, only where inline
content cites it. A table is a block of its own, which ends as
GitHub's table extension ends it, and each of its cells parses alone,
while the cells past the header's count, which GitHub drops, hold no
links.
- It tokenizes the raw HTML, in the order that GitHub renders it, as an
HTML parser does, to find the tags whose attributes hold targets and
anchors. A comment hides everything that renders up to its end, even
in later blocks, while a CDATA section, processing instruction, or
declaration ends at its first >. The tags that GitHub filters, such
as <script> and <iframe>, render as text.
- It parses each reference definition at the start of a paragraph whole,
within that paragraph, with its title, before the inline content that
follows, and accepts any destination without spaces, as GitHub does. A
definition counts where it renders, and wherever a rendered reference
uses it, even in a footnote that does not render. In heading text, a
reference link or image resolves only when a definition holds its
label, a citation renders as its footnote's number, and the delimiters
of emphasis and strikethrough match as cmark-gfm matches them, those
of each link's text alone.
- It decodes a destination as cmark does, trimmed and with its
character references before its backslash escapes, and an HTML
attribute as GitHub does, which keeps its backslashes, and its named
references without semicolons, literal, and drops only the leading
whitespace of a URL. As in HTML, the first attribute of each name
hides the others.
- Links into the openvmm submodule resolve against its pinned commit
when it is checked out and are skipped otherwise, as in the quality
job, whose checkout does not fetch submodules.
- It also resolves, from the repository root, every doc/ path, with any
anchor, that a tracked text file mentions. DOC_PATH_FIXTURES lists
the test fixtures that name missing documents, such as doc/notes.md
in scripts/test_nvx_tools.py, and an entry that its file no longer
needs fails the check. A mention followed by a character that could
extend the path, such as the * of a pattern, is ambiguous and is
skipped.
- It reports each problem with its file and line, as an error
annotation in GitHub Actions, and then exits with status 1.
scripts/test_markdown_links.py covers the slugs, the parsing, the
resolution in temporary repositories, including a submodule, the
fixtures, and the command line, and validate-nvx runs it on Linux and
Windows.
Retarget the README link to native-proxy-and-host-loopback, the only
broken link that the check found, and document the check in
doc/contribute.md, doc/setup.md, and doc/project-structure.md.
Fixes#563
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Nothing in CI checked the repository's relative Markdown links. #529
moved the design documentation, numbered its sections, and retargeted
every inbound link by hand, while an older link had already broken: the
MXC integration table in aci_edge_sandboxes/README.md linked the anchor
native-proxy-and-forwarded-ports of a heading that #512 had renamed to
"Native proxy and host loopback". GitHub opens a page at its top when an
anchor is missing, so such links break silently, and so do comments
that cite a document by path, as the citations of the removed time ABI
specification did (#562).
Add scripts/check_markdown_links.py, a standard-library check, and run
it in check-quality, whose job runs for every pull request that is
ready for review, including the documentation-only ones that are most
likely to break a link:
- It resolves every relative link and image target of the tracked
Markdown files, whether an inline link, a reference definition, or
the href of an HTML link or src of an image, against the files that
Git tracks, so a target that is untracked or differs in case, which
GitHub cannot serve, fails too. A directory resolves, and its anchors
are those of its README, whatever the README's case. An empty target,
such as that of [Self](), links to its own document, and an image's
anchor, such as GitHub's #gh-dark-mode-only, goes unchecked.
- It resolves each anchor as GitHub's script looks it up, in lowercase
and with the user-content- prefix of the ids that GitHub renders,
which the anchor may hold already, against the slugs that GitHub
generates from the rendered text of the Markdown and HTML headings,
including the numeric suffixes of repeated headings, and against the
id and name attributes of the HTML elements that GitHub keeps. Other
files accept only line anchors, such as #L10, within their length.
- It scans the blocks of each document as cmark nests them in block
quotes, list items, and GitHub's footnote definitions, with lazy
continuation lines and tabs that advance to the next multiple of four
columns, and strips their markers before it parses inline content. As
on GitHub, front matter, fenced and indented code, and the seven kinds
of HTML blocks hold no Markdown links, while the definitions and
headings inside those containers count.
- It parses inline content left to right as CommonMark does: code spans,
autolinks, including GitHub's bare ones, and raw HTML are atomic, each
destination is consumed with its title, and brackets match so that
links do not nest and an image's description holds no links. A
footnote renders, with its fn- and fnref- anchors, only where inline
content cites it. A table is a block of its own, which ends as
GitHub's table extension ends it, and each of its cells parses alone,
while the cells past the header's count, which GitHub drops, hold no
links.
- It tokenizes the raw HTML, in the order that GitHub renders it, as an
HTML parser does, to find the tags whose attributes hold targets and
anchors. A comment hides everything that renders up to its end, even
in later blocks, while a CDATA section, processing instruction, or
declaration ends at its first >. The tags that GitHub filters, such
as <script> and <iframe>, render as text.
- As GitHub does, it slugs the text that each heading holds in the tree
that libxml2's HTML parser builds from the rendered HTML. A start tag
closes only the elements that libxml2 lets it close, so a paragraph's
start tag closes a heading while a code block's does not, an end tag
closes no element of a higher priority than its own, and a heading
closes the heading that it starts in, so the text of a heading may run
on across blocks.
- It parses each reference definition at the start of a paragraph whole,
within that paragraph, with its title, before the inline content that
follows, and accepts any destination without spaces, as GitHub does. A
definition counts where it renders, and wherever a rendered reference
uses it, even in a footnote that does not render. In heading text, a
reference link or image resolves only when a definition holds its
label, a citation renders as its footnote's number, and the delimiters
of emphasis and strikethrough match as cmark-gfm matches them, those
of each link's text alone.
- It decodes a destination as cmark does, trimmed and with its
character references before its backslash escapes, and an HTML
attribute as GitHub does, which keeps its backslashes, and its named
references without semicolons, literal, and drops only the leading
whitespace of a URL. As in HTML, the first attribute of each name
hides the others.
- Links into the openvmm submodule resolve against its pinned commit
when it is checked out and are skipped otherwise, as in the quality
job, whose checkout does not fetch submodules.
- It also resolves, from the repository root, every doc/ path, with any
anchor, that a tracked text file mentions. DOC_PATH_FIXTURES lists
the test fixtures that name missing documents, such as doc/notes.md
in scripts/test_nvx_tools.py, and an entry that its file no longer
needs fails the check. A mention followed by a character that could
extend the path, such as the * of a pattern, is ambiguous and is
skipped.
- It reports each problem with its file and line, as an error
annotation in GitHub Actions, and then exits with status 1.
scripts/test_markdown_links.py covers the slugs, the parsing, the
resolution in temporary repositories, including a submodule, the
fixtures, and the command line, and validate-nvx runs it on Linux and
Windows.
Retarget the README link to native-proxy-and-host-loopback, the only
broken link that the check found, and document the check in
doc/contribute.md, doc/setup.md, and doc/project-structure.md.
Fixes#563
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Nothing in CI checked the repository's relative Markdown links. #529
moved the design documentation, numbered its sections, and retargeted
every inbound link by hand, while an older link had already broken: the
MXC integration table in aci_edge_sandboxes/README.md linked the anchor
native-proxy-and-forwarded-ports of a heading that #512 had renamed to
"Native proxy and host loopback". GitHub opens a page at its top when an
anchor is missing, so such links break silently, and so do comments
that cite a document by path, as the citations of the removed time ABI
specification did (#562).
Add scripts/check_markdown_links.py, a standard-library check, and run
it in check-quality, whose job runs for every pull request that is
ready for review, including the documentation-only ones that are most
likely to break a link:
- It resolves every relative link and image target of the tracked
Markdown files, whether an inline link, a reference definition, or
the href of an HTML link or src of an image, against the files that
Git tracks, so a target that is untracked or differs in case, which
GitHub cannot serve, fails too. A directory resolves, and its anchors
are those of its README, whatever the README's case. An empty target,
such as that of [Self](), links to its own document, and an image's
anchor, such as GitHub's #gh-dark-mode-only, goes unchecked.
- It resolves each anchor as GitHub's script looks it up, in lowercase
and with the user-content- prefix of the ids that GitHub renders,
which the anchor may hold already, against the slugs that GitHub
generates from the rendered text of the Markdown and HTML headings,
including the numeric suffixes of repeated headings, and against the
id and name attributes of the HTML elements that GitHub keeps. Other
files accept only line anchors, such as #L10, within their length.
- It scans the blocks of each document as cmark nests them in block
quotes, list items, and GitHub's footnote definitions, with lazy
continuation lines and tabs that advance to the next multiple of four
columns, and strips their markers before it parses inline content. As
on GitHub, front matter, fenced and indented code, and the seven kinds
of HTML blocks hold no Markdown links, while the definitions and
headings inside those containers count.
- It parses inline content left to right as CommonMark does: code spans,
autolinks, including GitHub's bare ones, and raw HTML are atomic, each
destination is consumed with its title, and brackets match so that
links do not nest and an image's description holds no links. A
footnote renders, with its fn- and fnref- anchors, only where inline
content cites it. A table is a block of its own, which ends as
GitHub's table extension ends it, and each of its cells parses alone,
while the cells past the header's count, which GitHub drops, hold no
links.
- It tokenizes the raw HTML, in the order that GitHub renders it, as an
HTML parser does, to find the tags whose attributes hold targets and
anchors. A comment hides everything that renders up to its end, even
in later blocks, while a CDATA section, processing instruction, or
declaration ends at its first >. The tags that GitHub filters, such
as <script> and <iframe>, render as text.
- As GitHub does, it slugs the text that each heading holds in the tree
that libxml2's HTML parser builds from the whole rendered document. A
start tag closes only the elements that libxml2 lets it close, so a
paragraph's start tag closes a heading while a code block's does not,
an end tag closes no element of a higher priority than its own, and a
heading closes the heading that it starts in. The text of a heading
may thus run on across blocks, and the end tag of an element that an
earlier block leaves open, such as a div, may close it.
- It parses each reference definition at the start of a paragraph whole,
within that paragraph, with its title, before the inline content that
follows, and accepts any destination without spaces, as GitHub does. A
definition counts where it renders, and wherever a rendered reference
uses it, even in a footnote that does not render. In heading text, a
reference link or image resolves only when a definition holds its
label, a citation renders as its footnote's number, and the delimiters
of emphasis and strikethrough match as cmark-gfm matches them, those
of each link's text alone.
- It decodes a destination as cmark does, trimmed and with its
character references before its backslash escapes, and an HTML
attribute as GitHub does, which keeps its backslashes, and its named
references without semicolons, literal, and drops only the leading
whitespace of a URL. As in HTML, the first attribute of each name
hides the others.
- Links into the openvmm submodule resolve against its pinned commit
when it is checked out and are skipped otherwise, as in the quality
job, whose checkout does not fetch submodules.
- It also resolves, from the repository root, every doc/ path, with any
anchor, that a tracked text file mentions. DOC_PATH_FIXTURES lists
the test fixtures that name missing documents, such as doc/notes.md
in scripts/test_nvx_tools.py, and an entry that its file no longer
needs fails the check. A mention followed by a character that could
extend the path, such as the * of a pattern, is ambiguous and is
skipped.
- It reports each problem with its file and line, as an error
annotation in GitHub Actions, and then exits with status 1.
scripts/test_markdown_links.py covers the slugs, the parsing, the
resolution in temporary repositories, including a submodule, the
fixtures, and the command line, and validate-nvx runs it on Linux and
Windows.
Retarget the README link to native-proxy-and-host-loopback, the only
broken link that the check found, and document the check in
doc/contribute.md, doc/setup.md, and doc/project-structure.md.
Fixes#563
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Nothing in CI checked the repository's relative Markdown links. #529
moved the design documentation, numbered its sections, and retargeted
every inbound link by hand, while an older link had already broken: the
MXC integration table in aci_edge_sandboxes/README.md linked the anchor
native-proxy-and-forwarded-ports of a heading that #512 had renamed to
"Native proxy and host loopback". GitHub opens a page at its top when an
anchor is missing, so such links break silently, and so do comments
that cite a document by path, as the citations of the removed time ABI
specification did (#562).
Add scripts/check_markdown_links.py, a standard-library check, and run
it in check-quality, whose job runs for every pull request that is
ready for review, including the documentation-only ones that are most
likely to break a link:
- It resolves every relative link and image target of the tracked
Markdown files, whether an inline link, a reference definition, or
the href of an HTML link or src of an image, against the files that
Git tracks, so a target that is untracked or differs in case, which
GitHub cannot serve, fails too. A directory resolves, and its anchors
are those of its README, whatever the README's case. An empty target,
such as that of [Self](), links to its own document, and an image's
anchor, such as GitHub's #gh-dark-mode-only, goes unchecked.
- It resolves each anchor as GitHub's script looks it up, in lowercase
and with the user-content- prefix of the ids that GitHub renders,
which the anchor may hold already, against the slugs that GitHub
generates from the rendered text of the Markdown and HTML headings,
including the numeric suffixes of repeated headings, and against the
id and name attributes of the HTML elements that GitHub keeps. Other
files accept only line anchors, such as #L10, within their length.
- It scans the blocks of each document as cmark nests them in block
quotes, list items, and GitHub's footnote definitions, with lazy
continuation lines and tabs that advance to the next multiple of four
columns, and strips their markers before it parses inline content. As
on GitHub, front matter, fenced and indented code, and the seven kinds
of HTML blocks hold no Markdown links, while the definitions and
headings inside those containers count.
- It parses inline content left to right as CommonMark does: code spans,
autolinks, including GitHub's bare ones, and raw HTML are atomic, each
destination is consumed with its title, and brackets match so that
links do not nest and an image's description holds no links. A
footnote renders, with its fn- and fnref- anchors, only where inline
content cites it. A table is a block of its own, which ends as
GitHub's table extension ends it, and each of its cells parses alone,
while the cells past the header's count, which GitHub drops, hold no
links.
- It tokenizes the raw HTML, in the order that GitHub renders it, as an
HTML parser does, to find the tags whose attributes hold targets and
anchors. A comment hides everything that renders up to its end, even
in later blocks, while a CDATA section, processing instruction, or
declaration ends at its first >. The tags that GitHub filters, such
as <script> and <iframe>, render as text.
- As GitHub does, it slugs the text that each heading holds in the tree
that libxml2's HTML parser builds from the whole rendered document. A
start tag closes only the elements that libxml2 lets it close, so a
paragraph's start tag closes a heading while a code block's does not,
an end tag closes no element of a higher priority than its own, and a
heading closes the heading that it starts in. The text of a heading
may thus run on across blocks, and the end tag of an element that an
earlier block leaves open, such as a div, may close it.
- It parses each reference definition at the start of a paragraph whole,
within that paragraph, with its title, before the inline content that
follows, and accepts any destination without spaces, as GitHub does. A
definition counts where it renders, and wherever a rendered reference
uses it, even in a footnote that does not render. In heading text, a
reference link or image resolves only when a definition holds its
label, a citation renders as its footnote's number, and the delimiters
of emphasis and strikethrough match as cmark-gfm matches them, those
of each link's text alone.
- It decodes a destination as cmark does, trimmed and with its
character references before its backslash escapes, and an HTML
attribute as GitHub does, which keeps its backslashes, and its named
references without semicolons, literal, and drops only the leading
whitespace of a URL. As in HTML, the first attribute of each name
hides the others.
- Links into the openvmm submodule resolve against its pinned commit
when it is checked out and are skipped otherwise, as in the quality
job, whose checkout does not fetch submodules.
- It also resolves, from the repository root, every doc/ path, with any
anchor, that a tracked text file mentions. DOC_PATH_FIXTURES lists
the test fixtures that name missing documents, such as doc/notes.md
in scripts/test_nvx_tools.py, and an entry that its file no longer
needs fails the check. A mention followed by a character that could
extend the path, such as the * of a pattern, is ambiguous and is
skipped.
- It reports each problem with its file and line, as an error
annotation in GitHub Actions, and then exits with status 1.
scripts/test_markdown_links.py covers the slugs, the parsing, the
resolution in temporary repositories, including a submodule, the
fixtures, and the command line, and validate-nvx runs it on Linux and
Windows.
Retarget the README link to native-proxy-and-host-loopback, the only
broken link that the check found, and document the check in
doc/contribute.md, doc/setup.md, and doc/project-structure.md.
Fixes#563
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Nothing in CI checked the repository's relative Markdown links. #529
moved the design documentation, numbered its sections, and retargeted
every inbound link by hand, while an older link had already broken: the
MXC integration table in aci_edge_sandboxes/README.md linked the anchor
native-proxy-and-forwarded-ports of a heading that #512 had renamed to
"Native proxy and host loopback". GitHub opens a page at its top when an
anchor is missing, so such links break silently, and so do comments
that cite a document by path, as the citations of the removed time ABI
specification did (#562).
Add scripts/check_markdown_links.py, a standard-library check, and run
it in check-quality, whose job runs for every pull request that is
ready for review, including the documentation-only ones that are most
likely to break a link:
- It resolves every relative link and image target of the tracked
Markdown files, whether an inline link, a reference definition, or
the href of an HTML link or src of an image, against the files that
Git tracks, so a target that is untracked or differs in case, which
GitHub cannot serve, fails too. A directory resolves, and its anchors
are those of its README, whatever the README's case. An empty target,
such as that of [Self](), links to its own document, and an image's
anchor, such as GitHub's #gh-dark-mode-only, goes unchecked.
- It resolves each anchor as GitHub's script looks it up, in lowercase
and with the user-content- prefix of the ids that GitHub renders,
which the anchor may hold already, against the slugs that GitHub
generates from the rendered text of the Markdown and HTML headings,
including the numeric suffixes of repeated headings, and against the
id and name attributes of the HTML elements that GitHub keeps. Other
files accept only line anchors, such as #L10, within their length.
- It scans the blocks of each document as cmark nests them in block
quotes, list items, and GitHub's footnote definitions, with lazy
continuation lines and tabs that advance to the next multiple of four
columns, and strips their markers before it parses inline content. As
on GitHub, front matter, fenced and indented code, and the seven kinds
of HTML blocks hold no Markdown links, while the definitions and
headings inside those containers count.
- It parses inline content left to right as CommonMark does: code spans,
autolinks, including GitHub's bare ones, and raw HTML are atomic, each
destination is consumed with its title, and brackets match so that
links do not nest and an image's description holds no links. A
footnote renders, with its fn- and fnref- anchors, only where inline
content cites it. A table is a block of its own, which ends as
GitHub's table extension ends it, and each of its cells parses alone,
while the cells past the header's count, which GitHub drops, hold no
links.
- It tokenizes the raw HTML, in the order that GitHub renders it, as an
HTML parser does, to find the tags whose attributes hold targets and
anchors. A comment hides everything that renders up to its end, even
in later blocks, while a CDATA section, processing instruction, or
declaration ends at its first >. The tags that GitHub filters, such
as <script> and <iframe>, render as text.
- As GitHub does, it slugs the text that each heading holds in the tree
that libxml2's HTML parser builds from the whole rendered document,
where the paragraphs of tight lists, as cmark finds them, have no
tags. A start tag closes only the elements that libxml2 lets it close,
so a paragraph's start tag closes a heading while a code block's does
not, an end tag closes no element of a higher priority than its own,
and a heading closes the heading that it starts in. The text of a
heading may thus run on across blocks, and the end tag of an element
that an earlier block leaves open, such as a div, may close it.
- It parses each reference definition at the start of a paragraph whole,
within that paragraph, with its title, before the inline content that
follows, and accepts any destination without spaces, as GitHub does. A
definition counts where it renders, and wherever a rendered reference
uses it, even in a footnote that does not render. In heading text, a
reference link or image resolves only when a definition holds its
label, a citation renders as its footnote's number, and the delimiters
of emphasis and strikethrough match as cmark-gfm matches them, those
of each link's text alone.
- It decodes a destination as cmark does, trimmed and with its
character references before its backslash escapes, and an HTML
attribute as GitHub does, which keeps its backslashes, and its named
references without semicolons, literal, and drops only the leading
whitespace of a URL. As in HTML, the first attribute of each name
hides the others.
- Links into the openvmm submodule resolve against its pinned commit
when it is checked out and are skipped otherwise, as in the quality
job, whose checkout does not fetch submodules.
- It also resolves, from the repository root, every doc/ path, with any
anchor, that a tracked text file mentions. DOC_PATH_FIXTURES lists
the test fixtures that name missing documents, such as doc/notes.md
in scripts/test_nvx_tools.py, and an entry that its file no longer
needs fails the check. A mention followed by a character that could
extend the path, such as the * of a pattern, is ambiguous and is
skipped.
- It reports each problem with its file and line, as an error
annotation in GitHub Actions, and then exits with status 1.
scripts/test_markdown_links.py covers the slugs, the parsing, the
resolution in temporary repositories, including a submodule, the
fixtures, and the command line, and validate-nvx runs it on Linux and
Windows.
Retarget the README link to native-proxy-and-host-loopback, the only
broken link that the check found, and document the check in
doc/contribute.md, doc/setup.md, and doc/project-structure.md.
Fixes#563
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Nothing in CI checked the repository's relative Markdown links. #529
moved the design documentation, numbered its sections, and retargeted
every inbound link by hand, while an older link had already broken: the
MXC integration table in aci_edge_sandboxes/README.md linked the anchor
native-proxy-and-forwarded-ports of a heading that #512 had renamed to
"Native proxy and host loopback". GitHub opens a page at its top when an
anchor is missing, so such links break silently, and so do comments
that cite a document by path, as the citations of the removed time ABI
specification did (#562).
Add scripts/check_markdown_links.py, a standard-library check, and run
it in check-quality, whose job runs for every pull request that is
ready for review, including the documentation-only ones that are most
likely to break a link:
- It resolves every relative link and image target of the tracked
Markdown files, whether an inline link, a reference definition, or
the href of an HTML link or src of an image, against the files that
Git tracks, so a target that is untracked or differs in case, which
GitHub cannot serve, fails too. A directory resolves, and its anchors
are those of its README, whatever the README's case. An empty target,
such as that of [Self](), links to its own document, and an image's
anchor, such as GitHub's #gh-dark-mode-only, goes unchecked.
- It resolves each anchor as GitHub's script looks it up, in lowercase
and with the user-content- prefix of the ids that GitHub renders,
which the anchor may hold already, against the slugs that GitHub
generates from the rendered text of the Markdown and HTML headings,
including the numeric suffixes of repeated headings, and against the
id and name attributes of the HTML elements that GitHub keeps. Other
files accept only line anchors, such as #L10, within their length.
- It scans the blocks of each document as cmark nests them in block
quotes, list items, and GitHub's footnote definitions, with lazy
continuation lines and tabs that advance to the next multiple of four
columns, and strips their markers before it parses inline content. As
on GitHub, front matter, fenced and indented code, and the seven kinds
of HTML blocks hold no Markdown links, while the definitions and
headings inside those containers count.
- It parses inline content left to right as CommonMark does: code spans,
autolinks, including GitHub's bare ones, and raw HTML are atomic, each
destination is consumed with its title, and brackets match so that
links do not nest and an image's description holds no links. A
footnote renders, with its fn- and fnref- anchors, only where inline
content cites it. A table is a block of its own, which ends as
GitHub's table extension ends it, and each of its cells parses alone,
while the cells past the header's count, which GitHub drops, hold no
links.
- It tokenizes the raw HTML, in the order that GitHub renders it, as an
HTML parser does, to find the tags whose attributes hold targets and
anchors. A comment hides everything that renders up to its end, even
in later blocks, while a CDATA section, processing instruction, or
declaration ends at its first >. The tags that GitHub filters, such
as <script> and <iframe>, render as text.
- As GitHub does, it slugs the text that each heading holds in the tree
that libxml2's HTML parser builds from the whole rendered document,
where the paragraphs of tight lists, as cmark finds them, have no
tags. A start tag closes only the elements that libxml2 lets it close,
so a paragraph's start tag closes a heading while a code block's does
not, an end tag closes no element of a higher priority than its own,
and a heading closes the heading that it starts in. The text of a
heading may thus run on across blocks, and the end tag of an element
that an earlier block leaves open, such as a div, may close it.
- It parses each reference definition at the start of a paragraph whole,
within that paragraph, with its title, before the inline content that
follows, and accepts any destination without spaces, as GitHub does. A
definition counts where it renders, and wherever a rendered reference
uses it, even in a footnote that does not render. In heading text, a
reference link or image resolves only when a definition holds its
label, a citation renders as its footnote's number, and the delimiters
of emphasis and strikethrough match as cmark-gfm matches them, those
of each link's text alone.
- It decodes a destination as cmark does, trimmed and with its
character references before its backslash escapes, and an HTML
attribute as GitHub does, which keeps its backslashes, and its named
references without semicolons, literal, and drops only the leading
whitespace of a URL. As in HTML, the first attribute of each name
hides the others.
- Links into the openvmm submodule resolve against its pinned commit
when it is checked out and are skipped otherwise, as in the quality
job, whose checkout does not fetch submodules.
- It also resolves, from the repository root, every doc/ path, with any
anchor, that a tracked text file mentions. DOC_PATH_FIXTURES lists
the test fixtures that name missing documents, such as doc/notes.md
in scripts/test_nvx_tools.py, and an entry that its file no longer
needs fails the check. A mention followed by a character that could
extend the path, such as the * of a pattern, is ambiguous and is
skipped.
- It reports each problem with its file and line, as an error
annotation in GitHub Actions, and then exits with status 1.
scripts/test_markdown_links.py covers the slugs, the parsing, the
resolution in temporary repositories, including a submodule, the
fixtures, and the command line, and validate-nvx runs it on Linux and
Windows.
Retarget the README link to native-proxy-and-host-loopback, the only
broken link that the check found, and document the check in
doc/contribute.md, doc/setup.md, and doc/project-structure.md.
Fixes#563
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
network.ingress.hostLoopback: "allow"without a caller-supplied forwarding list: the workload reaches host loopback through its gateway, subject to the egress policy, and the host reaches every TCP and UDP port on which the workload listens on a non-loopback address, on host127.0.0.1or::1alonenvx-ingressannouncer now also runs forvirtnet_ingress=host-loopback, and guest-loopback listeners stay privatehostLoopback: allowandhostLoopbackForwardsthroughnvx-rsand the ACI Edge Sandboxes OpenVMM backend to--host-loopback allowand up to 64 explicit TCP or UDP forwards; forwards need host-loopback access allowed, an egress default ofallow, and no deny rule over the guest network, each protocol's host ports and guest ports appear at most once, and the sandbox record keeps themFixes #276.
OpenVMM dependency
a44fcc2aa496cc9b50b15d3e593d02e27e04a4fb) and consomme: present IPv6 host peers inside the static subnet nanvix/openvmm#135 (7f225e2cd635bbd1e1839e587e659996433396c8), each one SSH-signed commit, both merged by fast-forwarding OpenVMMmain, which is now at the pinned revision7f225e2cd635bbd1e1839e587e659996433396c8, two commits pastdd8def143ddcbbf174719d851cd5f28cd07489a7, the private-network ingress revision thatdevpins1866919502ac4188cf66445bf3062b9f8409884c, whose separate publication protocol conflicted with Support private-network inbound access #275's. This is a re-implementation on Support private-network inbound access #275's mechanism, not a rebase, so it claims neither tree nor patch equivalence with the earlier revision. The roadmap index records positions 316 and 317Changes
guest/common/initstartsnvx-ingressforvirtnet_ingress=allowandvirtnet_ingress=host-loopbacknvx-rs:NetworkPolicygains the host-loopback access and validated loopback forwards, and the fake OpenVMM accepts--host-loopback-forwardSandboxSpec::with_host_loopback_forward,AciEdgeSandbox::provision_with) and persists the forwards in the sandbox record without changing its format versionhost-loopback-policymicroVM scenario checks, under an egress default ofdeny, the token and announcer, host clients of published IPv4 and IPv6 TCP listeners, UDP exchanges over IPv4 and IPv6 loopback, an explicit forward, guest-loopback privacy, and the snapshot rejectionhost_loopback_access_is_bidirectionalend to end, and the agent guest testdoc/run.md,doc/usage.md, the design documents, the ACI README, and the OpenVMM roadmap indexReview follow-ups
54b80b44: nvx-rs rejects a second forward of one protocol to the same guest port, which OpenVMM keys by guest port and could not bind87be52ceand3f9e5f0d: host-to-guest UDP over::1got no reply under an active egress policy, because OpenVMM presented host peers at link-local addresses that the guest answered from its link-local address. consomme: present IPv6 host peers inside the static subnet nanvix/openvmm#135 presents them inside the guest's subnet instead, and the scenario now exchanges UDP over IPv6 loopback; it fails with the previous pin5cfba311: nvx-rs rejects host-loopback access for a/30guest network, which holds only the gateway and the guest, so OpenVMM presents IPv4 host peers at the gateway there and IPv4 UDP replies to the host would not return through the published port; the ACI OpenVMM backend reports it aspolicy_validationValidation
On
5cfba311e9b5f4a6c59a815899830154fc2446d1, on Windows: thenvx-rsand ACI Edge Sandboxes gates (cargo fmt --check, clippy for all features and for the library without default features, tests for all features and default features, docs with-D warnings, and the MSRV 1.89 checks).On
3f9e5f0dcb10236a3d041b84ac634ccaf8631d1a, whose successor changes only Rust validation and documentation, on Windows:python scripts\nvx.py verifyruff checkandruff format --checkforscriptsand.github/specula;pyrightfor Linux and Windows: 0 errorspython -m unittest scripts/test_microvm_tests.py scripts/test_guest_ingress.py: 198 tests OK (14 skipped on Windows)7f225e2c:test-microvmhost-loopback-policy,private-network-ingress,ipv6-egress-policy,directional-network-policy,network-snapshot, andendpoint-policy-snapshotpassed, andtest-aci-edge-sandboxespassed 18/18On
54b80b44: the samenvx-rsand ACI Edge Sandboxes gates. Before the rebase onto the currentdev, whose new commits change neitherguest/, the microVM scenarios, nornvx-rs: ShellCheck and shfmt forguest/common/init.CI passed on
420f280e(https://github.com/microsoft/nvx/actions/runs/38425484006) and54b80b44(https://github.com/microsoft/nvx/actions/runs/38431878926), including the Linux/KVM, Linux/MSHV, and Windows/WHP microVM and platform jobs. The OpenVMM revisions' own gates are listed in nanvix/openvmm#134 and nanvix/openvmm#135.Known limitations
doc/run.mddocuments this./30IPv4 guest network has no free address for an IPv4 host peer, so OpenVMM presents it at the gateway, as it did before this PR, and the guest's UDP replies to host clients over IPv4 loopback do not return through the published port. nvx-rs and therefore ACI Edge Sandboxes reject host-loopback access for a/30; direct OpenVMM andnvx.pyuse accept it, anddoc/run.mddocuments the limit.Exact NVX head:
5cfba311e9b5f4a6c59a815899830154fc2446d1Exact OpenVMM head:
7f225e2cd635bbd1e1839e587e659996433396c8