Перейти к содержанию

ADR-011: Always-on method surface and launch presets

  • Status: accepted

Context

ADR-006 recorded an earlier design in which application feature profiles selected different HTTP capabilities. The implementation has since converged on one built-in method policy, while operators still need understandable launch choices for loopback, protected local use, and strict direct exposure.

Treating those launch choices as capability gates caused backend, UI, CORS, tests, and documentation to disagree about which methods were actually available. It also encouraged operators to infer that a less visible method was disabled when the server still exposed it.

The project simultaneously has a deliberate public-package transition: xferry is the product and import name, while the older generic src package still ships for 2.x compatibility.

Decision

The built-in runtime has one always-on method surface. Its method names, handler bindings, mutation/CORS policy, UI grouping, and exposure notes are owned by CoreMethodSpec. PING.supported_methods is the runtime availability contract; method_groups is presentation metadata, not a second capability system.

The local, local-secure, and public-direct launch presets select configuration defaults only:

  • local keeps the loopback HTTP behavior;
  • local-secure adds protected loopback defaults;
  • public-direct enables strict validation and finite capacity defaults for an operator-owned external topology.

Presets do not hide, enable, or disable methods. Advanced upload, NOTE, SMUGGLE, clear operations, and WebSocket notes therefore require the same deployment controls as the rest of the always-on surface. Public-direct validation is a posture gate, not a feature gate.

The current product, distribution, CLI, and public import name remains xferry. New public APIs and examples use xferry. The src package remains packaged and supported throughout the 2.x release line as a deprecated compatibility surface; its planned removal boundary is 3.0. Consumers migrate by replacing public src imports and legacy module invocations with their xferry equivalents before upgrading to 3.0.

ADR-006 is preserved as historical context and marked superseded by this decision.

Consequences

Positive

  • Runtime, CORS, PING, UI, tests, and documentation share one availability model.
  • Launch choices remain approachable without creating a misleading basic versus expert product split.
  • Operators can no longer treat a hidden control or old profile name as a security boundary.
  • The package migration has an explicit current name, compatibility window, and next-major removal boundary.

Negative

  • Every deployment must account for the complete sensitive method surface.
  • Applications that still import src must migrate during 2.x rather than assuming indefinite compatibility.
  • Older profile-oriented documentation and automation must be updated or clearly retained only as history.

Follow-up

  • Active documentation guards reject profile-era availability claims.
  • Documentation and examples must lead with xferry; compatibility tests keep src working through 2.x.
  • Any future capability gating or 3.0 package removal requires an explicit superseding decision and migration verification.