Repository navigation
Description
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.
- Canonical target specification
- Canonical target inventory: 68 product controls, three private bootstrap values, two process inputs, 27 internal policies and seven dedicated collections.
- Published proposal and implementation queue
- Published inventory JSON
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.
Metadata
Metadata
Assignees
Labels
Type
Projects
- StatusShow more project fieldsIn Progress
Activity
itlezy commentedon Nov 12, 2026
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.
itlezy commentedon Nov 12, 2026
Current binding operator decision for clean Beta3 configuration:
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.
itlezy commentedon Nov 12, 2026
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-runowns 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.itlezy commentedon Nov 12, 2026
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.itlezy commentedon Nov 12, 2026
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.--profileexplicitly 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.fix(metadata): seed explicit AICH fixture authority (RUST-CI-043)
fix(metadata): seed explicit AICH fixture authority (RUST-CI-043)
itlezy commentedon Nov 13, 2026
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.Standalone server preference updates are classified as empty.
Ed2kSettingsUpdate::is_emptyincrates/emulebb-settings/src/lib.rs:1192omitsuse_server_prioritiesandauto_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.Explicit null can disappear from a mixed NAT update. The NAT validator in
crates/emulebb-rest/src/route_body_metadata/validators.rs:521does not validate the nonnullableenabledandrequireInitialMappingbooleans.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.
itlezy commentedon Nov 13, 2026
Numeric documentation correction: the approved literal
change_me_123change_me_123change_me_123is 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.itlezy commentedon Nov 15, 2026
Parent allocation: two bounded repairs to the existing settings contract, based on current Rust main
23e685b87bb76db21489c9b1cc725dd0da4241c1.useServerPrioritiesandautoConnectStaticOnlyupdates. Their definitions and application already exist; the emptiness predicate omits them. Owner: server-preference-patch, reserved settingslib.rsand RESTtests/route_app.rs.enabledandrequireInitialMapping, including mixed updates with a valid sibling. Reuse the existing strict boolean validator. Owner: nat-patch-validation, reserved RESTroute_body_metadata/validators.rsandtests/route_body_validation.rs.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:20017under 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.
itlezy commentedon Nov 15, 2026
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.
itlezy commentedon Nov 15, 2026
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.
itlezy commentedon Nov 15, 2026
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.