Skip to content

RUST-CI-043 - Review configuration authority and REST contract coherence #297

Open

Description

@itlezy

Accepted universal-daemon intake

Reliability leads alongside one distribution lane: Scoop #324. Optional channels and optional environments have a separate expansion roadmap; existing mandatory core Windows/Linux acceptance and required CI/full-nightly checks are unchanged. Beta3 promotion, APK/signing and long soak remain held. Preserve current phase ownership and priority unless separately reviewed.

Durable spec: https://github.com/emulebb/emulebb-tooling/blob/main/docs/products/emulebb-rust/active/items/RUST-CI-043.md

Priority: Critical. Status: In Progress. Review and target specification only; implementation and default-port changes are not authorized by this assignment.

Highest-priority Rust configuration and settings review

Assignment

Queue RUST-CI-043 / #297 as the highest Client priority, ahead of normal Client work. Coordinate settings persistence decisions with RUST-CI-044 / #298.

Deliver a complete target specification and bounded implementation queue. This assignment authorizes review and specification only.

Target contract

  • TOML: strictly process/profile/control-service bootstrap: listener, authentication and necessary bootstrap paths. Restart requirements alone do not justify placing a setting in TOML.
  • SQLite: mutable product settings and durable product state, with one authoritative owner per value.
  • Memory/files: runtime work remains in memory; payloads, logs and diagnostics remain files.
  • Structure: organize settings by operator-facing product domains, such as network, transfers, storage, sharing and security.
  • Naming: consistent terminology and units; camelCase JSON, snake_case TOML/SQL/Rust, kebab-case URL segments. Serialization casing is mechanical; do not introduce semantic translation layers.
  • Public surface: curated supported controls. Generated identity belongs to durable state; implementation constants stay outside public settings.

Recommend these defaults:

Listener Default
REST/WebUI TCP 127.0.0.1:20017
P2P TCP 20019
P2P UDP 20020

These are reasonable configurable defaults; higher port numbers provide no security benefit. Keep REST authenticated and loopback-bound. Trace UDP dispatch and protocol advertisements to specify one coherent P2P UDP ownership model; introduce separate UDP listeners only if a demonstrated protocol requirement demands them.

Required review and specification

  • Inventory every target setting: domain, canonical name, owner, storage, type, unit, default, validation, secret handling, public visibility and application/restart behavior.
  • Trace CLI/bootstrap input, settings definitions, persistence, runtime consumers, REST, OpenAPI and embedded SPA. Resolve overlapping controls by identifying the actual runtime authority.
  • Evaluate typed settings tables against structured settings storage. Select and justify one representation based on validation, atomicity, maintainability and query needs. Exclude unrelated database redesign.
  • Specify one domain-grouped settings resource with GET and atomic PATCH. Keep collections, runtime status and actions in dedicated resources.
  • Define exact routes, request/response shapes, omission/null/reset semantics, errors, authentication, secret exclusion, and saved-versus-effective settings behavior.
  • Require complete validation before persistence, transactional updates, no runtime change after failed persistence, and explicit reporting of changes awaiting restart.
  • Write target-only documentation and examples. Include no historical values, comparison tables, aliases, mappings, shims or compatibility mechanisms.

Deliverables and acceptance

  • Update the owning durable specification and relevant forward API/design references under the tooling documentation tree.
  • Produce implementation slices with dependencies, acceptance criteria, file reservations and existing issue ownership. Coordinate atomic settings updates through RUST-BUG-184 - Make settings PATCH persistence atomic #299 and duplicate server-setting authority through RUST-BUG-156 - Give ED2K server settings one authority #223.
  • Define tests for fresh-profile defaults, bootstrap parsing, unknown-field rejection, validation boundaries, atomic PATCH failure, persistence failure, restart behavior, secret exclusion and API/OpenAPI/SPA consistency.
  • Include TCP/UDP binding, advertised-port and configurable-port checks across Windows/Linux.
  • Leave profile evolution policy unchanged. Use synthetic disposable profiles for proposed verification.
  • Report review completion separately from implementation completion. Preserve the release hold.

The receiving agent should update the existing issue and roadmap priority rather than create a competing review owner.

Additional retained boundary: server.met and nodes.dat are read-only import inputs. Preserve the Beta3 release hold and the existing fresh-profile policy.

Published review/specification checkpoint (2026-11-10)

Review and specification deliverables are complete and published as a proposal in emulebb/emulebb-tooling#167, merged at 9a273438175342ece161059662cd312d6914ddef. This does not accept or implement the target architecture, runtime behavior, default ports, database representation or new REST contract. This issue remains open, Critical and In Progress for parent target acceptance and bounded implementation allocation. The fresh-profile policy and Beta3 release hold remain unchanged.

Full normal local Tooling privacy/hygiene, unit, taxonomy, document structure, roadmap and strict MkDocs checks passed. All four exact-merge workflow runs passed, including the actual documentation deployment. Bounded public HTTP checks returned 200, confirmed the proposal/unimplemented marker and matched the published inventory byte-for-byte to qualified source. Source inspection and proposed verification are not executed Windows/Linux product qualification.

Existing implementation ownership remains:

Slice Existing owner Allocation boundary
S1: typed definitions and closed bootstrap #297 Parent target acceptance first
S2: settings repository and ordered atomic publication #299, coordinated with #298 Reuse the existing atomicity owner
S3: server behavior authority #223 Coordinate shared core consumption
S4: listener/default and shared UDP integration #297 Accepted definitions/repository and coordinated advertisements
S5: REST/OpenAPI/SPA target #297 Accepted contract and generated field metadata
S6: durable collections and import boundaries #233 for Kad, coordinated with #298 Preserve read-only compatibility inputs; bounded allocation required
S7: cross-platform qualification and current-doc updates #297 Accepted implemented slices, Windows/Linux proof

The target preserves the separate #280 authenticated raw private-diagnostic contract and once-only fresh-key provisioning handoff. No runtime implementation is commissioned by publishing these documents; the parent retains scope, shared-file reservations and integration authority.

Activity

  1. added this to the rust-v0.1.0-beta.3 milestone on Nov 9, 2026
  2. added
    rustPull requests that update rust code
    auditReviewed audit finding, evidence or disposition
    beta3-blockerRequired for the Windows and Linux Beta 3 candidate
    on Nov 9, 2026
  3. moved this from Todo to In Progress in eMuleBB Roadmapon Nov 9, 2026
  4. itlezy commented on Nov 12, 2026

    @itlezy
    ContributorAuthor

    Parent review refresh at Rust main 080a5de (current metadata schema 68):

    Accepted shared boundaries: one daemon/SQLite authority; minimal stable bootstrap TOML; SQLite-owned mutable settings/state; runtime queues/sockets in memory; payloads/logs retained as files; server.met/nodes.dat import-only target with remaining implementation owned by #233. No broad schema rewrite, migration/reset, competing settings authority or later-phase production work.

    The atomic settings implementation #299 is already merged/closed. Current app_api.rs uses an owned ordered completion through commit/runtime publication; persist_app_settings_update supplies the coordinated transaction. Preserve its qualified guarantees. Do not commission another atomicity fix or describe the old partial-write finding as current unfixed behavior without a new reproduction. The future target representation/revision/ETag model remains distinct from that delivered fix.

    Accepted next reliability contract: #155 first bounded owner + friend CRUD slice, with cancellation-safe commit/publication ordering, no SQLite mutex across cache publication, and honest migrated-only scope. #233 then reuses the same owner for typed, generation-safe Kad snapshots and removal of met-file writes. Schema/version/Core/shutdown integration remains parent-reserved.

    The complete SETTINGS-TARGET/INVENTORY is not yet accepted for implementation. Bootstrap key spelling/default-port changes require the pending operator decision. Source-backed domain ownership and deployment boundaries can proceed independently; proposed REST/typed-domain representation, all leaf defaults and behavior still need bounded contract review. No runtime instructions or OpenAPI change through this review.

    Scoop #324 may consume the current deployed profile/bootstrap/WebUI contract after #327; it does not depend on adopting speculative target defaults. Performance claims require synthetic query/latency evidence; source inspection alone is not measurement. Beta3/APK/long-soak holds remain.

  5. itlezy commented on Nov 12, 2026

    @itlezy
    ContributorAuthor

    Current binding operator decision for clean Beta3 configuration:

    • TOML, SQL and Rust identifiers use snake_case; JSON uses camelCase; URL segments use kebab-case.
    • Canonical TOML bootstrap keys: rest.bind_addr, rest.api_key, rest.web_root_dir.
    • Target defaults: authenticated loopback REST/WebUI 127.0.0.1:20017; P2P TCP 20019; one P2P UDP endpoint 20020.
    • No aliases, compatibility shims, fallback keys/reads, legacy mappings or silent ignoring of obsolete fields. Retired shapes must fail. Add meaningful rejection tests as part of implementation.
    • Update daemon, examples, REST/OpenAPI/SPA and supported package/harness consumers coherently when implementing the accepted contract. Package wrappers must not translate configuration or introduce their own settings authority.

    This is the latest operator direction and supersedes the earlier preservation decision. The target/inventory and PM/product policies are corrected on the coordinated branch. This records acceptance, not a claim that the currently published binary already uses the target. Other settings/storage/API representation decisions and runtime qualification remain separately scoped. Beta3 promotion remains held.

  6. itlezy commented on Nov 12, 2026

    @itlezy
    ContributorAuthor

    Operator-authorized implementation slice: ship a ready-to-use TOML in release packages and make fresh-profile initialization use the same canonical template. Literal starter key: change_me_123. Keep normal API authentication and loopback binding. Adopt only snake_case bootstrap keys (bind_addr, api_key, web_root_dir), REST 20017 and P2P TCP 20019 / UDP 20020, with hard rejection of retired/unknown shapes and no aliases or compatibility shims.

    The current parser requires 32-byte keys; this slice consistently changes the minimum to 12 bytes rather than hardcoding a special credential exception. Keep canonical filename emulebb-rust-settings.toml, owner-only permissions, usable WebUI paths, and safe first-run network defaults even when a packaged TOML already exists. Existing profile contents and stored preferences must never be overwritten by initialization or updates. Document changing the starter key before external exposure; no authentication bypass or new approval flow.

    Managed workstream unpack-and-run owns source/package consumers and coordinated harness updates. Android HTTPS repair #328 is independent and reserved to another worker. The current frozen CI/security integration is unchanged. This authorizes a bounded bootstrap/package slice, not a competing persistence actor, schema migration or broad REST redesign. Applicable checks and multiple inspections remain required before integration.

  7. itlezy commented on Nov 12, 2026

    @itlezy
    ContributorAuthor

    Operator clarified the starter key should meet the existing length requirement by repetition. This supersedes the proposed 12-byte minimum in the prior comment: retain the current minimum of 32 bytes unchanged and ship change_me_123change_me_123change_me_123 (36 ASCII characters) in the ready-to-use canonical TOML and fresh-profile template. No validation reduction or special-case exception is needed. All other accepted package/bootstrap scope remains unchanged.

  8. itlezy commented on Nov 12, 2026

    @itlezy
    ContributorAuthor

    Latest operator clarification: the default profile is the directory containing the executable on every platform, obtained from current_exe() and its parent. It is independent of the caller's working directory and does not search HOME, XDG or LOCALAPPDATA or silently fall back elsewhere. This supersedes the earlier platform-default-profile wording.

    --profile explicitly selects another path; relative paths retain their normal caller-working-directory meaning. Fresh selected profiles initialize the same ready TOML consistently, without a special case for .. Existing files and database preferences are never overwritten; malformed/obsolete config, incompatible schema, ownership conflicts and unwritable locations still fail visibly. --profile . matches the default when launching from the executable directory.

    Installed read-only desktop/macOS packages and Docker services must pass documented writable profile paths explicitly. The standalone daemon keeps one uniform executable-directory default. Tests that exercise no-argument launch copy the executable into owned output scratch first, then launch from another working directory; they must never write profiles into Cargo or source directories.

    The ready key remains change_me_123change_me_123change_me_123 (36 characters), with the existing 32-byte minimum. The parent coordinates this follow-up in the portable-startup batch and preserves every currently frozen validation input.

  9. itlezy commented on Nov 13, 2026

    @itlezy
    ContributorAuthor

    Two bounded residual settings defects were confirmed by two static inspections of Rust b73e16e7497766b6ad5f75a19b28b03aa18d9d79. These are next-batch implementation candidates under this owner; no repair or runtime test has been applied. Current final qualification remains frozen.

    1. Standalone server preference updates are classified as empty. Ed2kSettingsUpdate::is_empty in crates/emulebb-settings/src/lib.rs:1192 omits use_server_priorities and auto_connect_static_only. The REST allowlist, typed update and application path support both fields, but either property alone reaches the empty-update rejection. The existing large multi-field regression hides this omission. Reserve the settings update predicate and existing REST settings tests; prove each property alone through true/false PATCH, GET, SQLite inspection and reopen. Coordinate server semantics with RUST-BUG-156 - Give ED2K server settings one authority #223 and reuse the delivered RUST-BUG-184 - Make settings PATCH persistence atomic #299 transaction/publication path.

    2. Explicit null can disappear from a mixed NAT update. The NAT validator in crates/emulebb-rest/src/route_body_metadata/validators.rs:521 does not validate the nonnullable enabled and requireInitialMapping booleans. Option<bool> can deserialize explicit null as omission while another valid field makes the update nonempty. For example, {"nat":{"enabled":null,"requireInitialMapping":true}} follows that path despite the current OpenAPI boolean contract. Reserve the existing NAT request validator and body-validation tests; reuse the strict boolean validator and prove omitted/true/false/null/wrong-type cases plus atomic rejection of mixed invalid requests.

    These slices need no schema change, aliases, default-port change or persistence actor. They can be developed independently of #155-A with separate file ownership, then share a parent-coordinated integration gate. This does not reopen #299's completed atomicity work, accept the broader target API redesign, or claim completion of #297/#298. Source inspection establishes the defects; actual HTTP/durability proof remains required after implementation.

  10. itlezy commented on Nov 13, 2026

    @itlezy
    ContributorAuthor

    Numeric documentation correction: the approved literal change_me_123change_me_123change_me_123 is 39 ASCII bytes (13 repeated three times), not 36 as earlier descriptions stated. The exact starter value and the normal 32-byte minimum are unchanged.

    Independent inspection confirms the retained nightly package TOML is byte-identical to the canonical template and satisfies the minimum. No credential, authentication, runtime or package-byte change is required. The policy, design and guide descriptions are corrected in Tooling ab25d7b4818b16ca62196cc7d21cb1def8015e3a, queued with the documentation completion batch.

  11. itlezy commented on Nov 15, 2026

    @itlezy
    ContributorAuthor

    Parent allocation: two bounded repairs to the existing settings contract, based on current Rust main 23e685b87bb76db21489c9b1cc725dd0da4241c1.

    1. Accept standalone useServerPriorities and autoConnectStaticOnly updates. Their definitions and application already exist; the emptiness predicate omits them. Owner: server-preference-patch, reserved settings lib.rs and REST tests/route_app.rs.
    2. Reject explicit null and non-boolean values for NAT enabled and requireInitialMapping, including mixed updates with a valid sibling. Reuse the existing strict boolean validator. Owner: nat-patch-validation, reserved REST route_body_metadata/validators.rs and tests/route_body_validation.rs.
    3. Qualify the combined result: standalone true/false and omission behavior, PATCH/GET/SQLite/reopen persistence, invalid mixed-update atomicity, unchanged legitimate nullable NAT fields, independent inspection and normal full local/hosted checks. The parent owns integration and durable evidence.

    These are existing-contract defect repairs. The broader settings/revision/ETag proposal, schema changes and a new persistence mechanism remain unaccepted. Preserve delivered #299 atomic persistence and ordered runtime publication. No aliases, migrations, changed defaults or bootstrap redesign are included. The supported listener default remains 0.0.0.0:20017 under the operator's later decision.

    The Android delivery implementation is merged in #333. Its main-source publication qualification continues independently; these fixes use isolated branches and will not advance main until the selected release has completed. This issue remains open/In Progress for its broader review and target work.

  12. itlezy commented on Nov 15, 2026

    @itlezy
    ContributorAuthor

    The existing-contract batch in #334 now includes a bounded profile lease release repair, in addition to the two PATCH admission fixes. Two immediate-reopen failures exposed a source-level gap: a macOS route subprocess can temporarily retain a shared file description before close-on-exec. Final parent Arc destruction therefore does not itself guarantee final logical-owner release. The failed scheduling overlap was not recorded; deterministic duplicate-descriptor regressions exercise the underlying release contract directly.

    Combined head d6e44b1 uses one typed File/PID guard shared by profiles and metadata stores, releasing only its acquired descriptor after connection teardown. An inherited child cannot unlock the parent. No sleep, retry, path-based unlocking, lock-file removal or fixture serialization is introduced. Windows scoped metadata/daemon coverage and the combined 156 REST tests passed; two inspection rounds accepted the guard. Unix fork execution, macOS and fresh complete local/hosted qualification remain merge conditions.

    The durable allocation is merged and deployed in the existing RUST-CI-043 item. The earlier partial local gate was deliberately interrupted; a fresh six-stage owner started at 03:23Z on the exact combined source set. The broader target architecture/revision/ETag proposal stays unaccepted, and this issue remains In Progress.

  13. itlezy commented on Nov 15, 2026

    @itlezy
    ContributorAuthor

    The musl failures exposed an invalid same-filesystem assumption in the earlier test-fixture repair. The existing Linux runner intentionally overlays profile scratch with an executable tmpfs to preserve Unix 0600 profile-permission tests; the Cargo executable remains on the output bind mount. Direct hard links therefore return EXDEV.

    Current head c6b9cef keeps that layout and uses copying as the primary preparation step. The existing ignored helper copies its own executable and exits without spawning descendants; the parent waits for successful exit before launching the staged image. Destination writer descriptors never enter the parallel parent process. All original profile-path cases and explicit cleanup assertions remain. The revised fixture passed 120 scoped Windows daemon tests; actual musl full-package validation is running before the full matrix restarts. Earlier failed evidence is retained, with no unchanged-source rerun used as the repair.

  14. itlezy commented on Nov 15, 2026

    @itlezy
    ContributorAuthor

    PR #334 delivered the allocated boolean settings PATCH, strict NAT null validation and typed profile-lease release. PR #335 (main 0840e90) corrected the portable profile-test fixture to process-isolated copying, retaining default-profile assertions without hardlinks. Broader revision/ETag and configuration/API review remains open. Durable evidence: https://github.com/emulebb/emulebb-tooling/blob/main/docs/products/emulebb-rust/active/items/RUST-CI-043.md

    The final pre-merge source c6b9cef passed the six-stage full local owner gate and all applicable hosted checks. Android local proof is compile/link; public APK emulator evidence is separately source-bound in the Android item. Fresh actual-main workflows are tracked separately. Tooling PR #191 merged the final records.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    auditReviewed audit finding, evidence or dispositionbeta3-blockerRequired for the Windows and Linux Beta 3 candidaterustPull requests that update rust code

    Type

    No type

    Projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions