Skip to content

feat: filter operations to hide internal endpoints - #18

Merged
includeamin merged 7 commits into
mainfrom
operation-filter
Nov 21, 2026
Merged

includeamin merged 7 commits into
mainfrom
operation-filter

Conversation

@includeamin

Copy link
Copy Markdown
Owner

Summary

  • New filter config, global (merge.filter) and per source (sources[].filter), with include (allow-list) and exclude rules. A rule matches an operation by path glob, tag, operationId, or a truthy vendor extension (x-internal) on the operation or its path item.
  • Filters run per source before the merge, so a hidden operation can never cause a conflict (two services can both expose /internal/metrics under the default error strategy).
  • Pruning: after removal, components (schemas, parameters, responses, ...), security schemes and tags that were used before and are unused after are removed. Cycles and discriminator.mapping targets are handled. Things that were never referenced to begin with are left alone, and sections or lists emptied by pruning are dropped.
  • Same behaviour in the CLI, library and playground (logic is in the pure core crate). New "Hide internal endpoints" playground example.
  • Nothing is hidden by default; configs without a filter produce identical output.

Semantics

  • Any criterion in a rule matches (OR). exclude rules from both levels apply and exclude wins. include rules from both levels must all match (they narrow).
  • * matches within one path segment, ** across segments; {id} is literal. Globs do not apply to webhooks.
  • A path with no remaining operations is removed; other path-item keys (e.g. shared parameters) stay while any operation remains.
  • Config errors name the key: unknown keys, rules with no entries, paths not starting with /, extensions not starting with x-, empty tag or operation-id strings.

Notes

  • Source and MergeConfig gain a filter field. That is a small breaking change for library users who construct them by hand.
  • The filter does not scrub descriptions, examples, servers, info or vendor extensions, which the README says explicitly. External documents referenced only by hidden operations are still loaded.
  • A real bug caught by a test: serde_json::Map::remove with preserve_order is a swap-remove and reordered surviving paths; the filter uses an order-preserving removal.

Test plan

  • cargo test --workspace (config validation, glob and rule matching, removal semantics, pruning including cycles and discriminator mappings, filter_source combining levels, CLI end-to-end where two services both expose /internal/metrics, source-level include, and the unfiltered config still conflicting, wasm test)
  • cargo clippy --workspace --all-targets -- -D warnings and cargo fmt --check
  • cd web && npm test (82 tests, including that the example's output contains no trace of the hidden endpoints), npm run typecheck, npm run e2e

@includeamin
includeamin merged commit b9fd992 into main Nov 21, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant