cfal
a150125c6b
* feat(config): add conditions while preserving mask rules Accept conditions alongside the existing masks and mask spellings, rejecting conflicting matching fields and flat-source combinations. Normalize all forms into the existing predicate engine. Add explicit masks leaves for composed expressions and source groups. Keep simple address exports compact and serialize richer rules under conditions. Cover round-trips, nested source discovery, controller payloads, warning-free compatibility, and routing across accepted and rejected reloads. * docs(routing): explain conditions and compatible mask syntax Document expression composition, conflicting fields, source shorthand, and canonical serialization in English and Chinese. Record the controller diagnostic shape in the changelog. Add a complete conditions example, validate it through the native configuration pipeline, and show conditions in the rule-source example. * fix(config): clarify invalid rule conditions diagnostics Name the mutually exclusive matching fields explicitly, including legacy aliases, instead of reporting an unwritten duplicate conditions key. Explain that nested masks leaves accept only strings or nonempty string lists, with regression tests for JSON/YAML conflicts and invalid leaf shapes. * refactor(tests): simplify rule conditions coverage Stage all spelling and format variants before checking their shared canonical form. Restore that form once while preserving per-variant compilation and the complete decision matrix. Remove conflict inputs already covered by stronger diagnostic assertions, clarify controller payload names, and validate all five rule forms in one fixture per CLI mode. * fix(rules): correct source-group predicate guidance Recommend the rule_source_group predicate without a masks wrapper so the rename hint works in nested expressions and source groups. Cover the suggested syntax and diagnostic in regression tests. Update both documentation locales to describe source-group references under conditions or masks, including boolean composition.
shoes documentation
This Starlight project is the source for https://shoes-rs.github.io/. Documentation is authored with shoes, not copied into the publication repository. The publication workflow resolves an exact shoes commit, runs npm ci and npm run check here, then deploys docs/dist/ to GitHub Pages. The site repository owns source selection and publication; this repository owns the content. Development publication follows successful documentation CI on master, with a pinned-commit override available in the site repository.
Local development
Use Node 24 (see .node-version):
cd docs
npm ci
npm run dev
npm run check
npm run build writes docs/dist/. npm run check builds the site, checks both locales, internal page and heading links (including links from README and CHANGELOG), translated-page coverage and code-snippet parity, and every example's copy-button payload against its YAML source. These checks do not fetch external URLs or validate a running shoes process. Rust CI separately parses all tracked YAML examples and fully validates a curated subset through the native configuration pipeline. npm run preview serves the built site, including its search index. Development and preview servers bind to all interfaces for VM access; use them only on a trusted network. For loopback-only access, run npm exec -- astro dev --host 127.0.0.1 (or replace dev with preview).
SHOES_DOCS_REF is the full lowercase shoes commit SHA shown on every page and in page metadata; an invalid explicit value fails the build. Without it, the build uses the local Git revision; links describe that committed revision, not uncommitted edits. If no revision is available, source links are omitted. SHOES_DOCS_LABEL is an explicit publication label, for example 1.2.0 or dev. Without it, all builds are labeled dev (unreleased). Do not infer release status from Cargo.toml.
For now, / contains only development documentation, without a version selector. Start versioned documentation with the first release containing buildable docs: keep release builds pinned, put development builds under /dev/, and publish all retained versions in one Pages artifact. That requires base-aware links and isolated search indexes before enabling a selector. Do not relabel current documentation as an older release; earlier releases require a reviewed documentation backport.
Authoring contract
- Keep new configuration guidance beside the parser/validator change in one shoes PR. The site is the configuration reference; keep README as its entry point.
- Keep English pages at the site root and their Simplified Chinese counterparts under
src/content/docs/zh-cn/. Use the built-in language selector; keep translated links within/zh-cn/and update both languages when behavior changes. - Use one page per protocol under
src/content/docs/protocols/, with separate server and client sections where supported. Put shared fields inconfig/, routing inrouting/, and operational behavior inoperations/. Link rather than duplicate. - Lead with a usable example. For complete files, import tracked
../examples/*.yamlas raw text into Starlight'sCodecomponent, as infirst-config.mdx. These snippets have copy buttons and are compiled from the same source that CI checks. Keep ordinary explanations in.md; use.mdxonly for imports or components. - Mark schema sketches and partial fragments as illustrative, not runnable. Document accepted values, requiredness, omission/default behavior, units, constraints, and client/server differences. Do not put real credentials in tracked examples.
- Extend the native example tests when a new complete example can be validated without external services. Do not treat parsing alone as runtime validation; certificates, routes, sockets, and platform support may still fail.
- Keep dependencies exact in
package.jsonand commitpackage-lock.json. Introduce generated field reference or JSON Schema only after a scoped pilot accounts for custom deserializers and runtime defaults. The Rust validator remains authoritative.
Example pages and the catalog are generated from examples/*.yaml by one shared
Starlight page template. Adding a tracked YAML example automatically adds its
copyable page; do not add a second Markdown copy. Use /examples/filename/
(without .yaml) to link to it. The header shows the documentation label, source
revision, and GitHub repository link on every page, including mobile layouts.
The former monolithic configuration reference was separated by topic without changing its field semantics. When editing a page, check the corresponding src/config type and validator; a rendered reference is not proof that a setting still exists.