mirror of
https://github.com/vicliu624/trail-mate.git
synced 2026-11-11 14:47:39 +00:00
Trail Mate Dev
6e613e382e
Compose the CM0 fullscreen application and standard Debian package, align the Cardputer Zero shell, and share protocol, configuration, audio and storage services with embedded targets through existing platform seams. Add the paginated on-device TMAP creator using Center's published producer, private workspace recovery and direct keyboard shortcuts. Preserve unfinished management work behind its existing opt-in capability. Include native, ARM and shared-core regression fixtures, integration records, packaging helpers and dependency/license updates. Keep local build trees, device credentials, produced packages and validation logs outside version control. Validation before integration: ESP stack hygiene, Reticulum scope guard, staged whitespace checks and GitNexus scope audit. Prior device/build evidence and remaining hardware/package boundaries are recorded in the acceptance documents.
93 lines
5.2 KiB
Markdown
93 lines
5.2 KiB
Markdown
# Linux HostLink staged uploads
|
|
|
|
The native management worker now implements TransferBegin (32), TransferChunk
|
|
(33), TransferStatus (34), TransferFinish (35) and TransferAbort (36), using the
|
|
shared upload protocol, resources, dual journal store, chunk writer, session and
|
|
seal task. Capabilities lists these operations only when the crypto-backed upload
|
|
adapter is available. An OpenSSL-free build retains explicit Unsupported stubs.
|
|
|
|
## Ownership and storage
|
|
|
|
One connection worker owns the transient coordinator. Its current upload is bound
|
|
to a nonzero session ID, upload ID, current device-author generation and SHA-256
|
|
of the combined author public key. Device identity is reread before operations;
|
|
a changed key or generation cannot continue an old upload. Another live session
|
|
cannot append, inspect, finish or abort that owner. A process-wide file lease also
|
|
prevents another application instance from concurrently admitting a writer into
|
|
the same configured storage root.
|
|
|
|
This is session/transaction ownership inside the configured HostLink connection,
|
|
not remote-user authentication. Device-author proof alone grants no mutation
|
|
rights. This stage writes quota-bound candidates only; it does not change working
|
|
configuration, private identities or published routes.
|
|
|
|
All filenames derive from the shared upload kind and 16-byte ID. The Linux I/O
|
|
adapter anchors access at a configured root descriptor, walks directory components
|
|
with `openat` and `O_NOFOLLOW`, rejects non-regular/hard-linked leaves, and uses
|
|
close-on-exec descriptors. Root device/inode checks invalidate access after media
|
|
replacement even when the pathname is reused. File data and containing-directory
|
|
metadata are synced before durable acknowledgement. New candidates are exclusive;
|
|
only validated alternating journal slots may be rewritten.
|
|
|
|
The shared per-kind limits and directory quota count unknown/orphan entries too.
|
|
The adapter supports KML, manifest, IP receipt, attachment index/resource/bindings
|
|
and signed-manifest kinds without board-specific directories or interface names.
|
|
It never takes a filename from client content.
|
|
|
|
## Progress, recovery and cancellation
|
|
|
|
Chunks are limited to 320 bytes and acknowledge the shared durable offset. Exact
|
|
duplicate chunks are idempotent; conflicting duplicates, gaps and overlapping
|
|
unacknowledged ranges fail. Journal publication follows file syncing. Recovery
|
|
uses the latest valid journal and permits a bounded unacknowledged file tail to
|
|
be overwritten from the recorded durable offset, without silently truncating
|
|
unrelated/orphan data.
|
|
|
|
Finish starts bounded background hashing on the existing worker. Polls retain
|
|
the exact transfer ID/offset; Sealed is returned only after full digest verification
|
|
and journal publication. A recovered Sealed journal is not file proof: Begin
|
|
returns unsealed progress while current bytes are rehashed. Failed hashes remain
|
|
errors and retain an owned abort path.
|
|
|
|
Close, disconnect, stop or the shared 30-second idle deadline release transient
|
|
ownership and cancel hashing while preserving durable files. A fresh Begin may
|
|
recover matching bytes under current device identity. Explicit Abort removes only
|
|
the owner's candidate and journals. Failed cleanup preserves its error state;
|
|
it never broadens deletion to unknown files.
|
|
|
|
## Verification
|
|
|
|
The C++ fixture covers duplicate/conflicting chunks, gaps, wrong sessions,
|
|
competing writers, crash-tail recovery, recovered-seal revalidation, digest failure,
|
|
abort, expiry/rebind, identity changes, all seven kinds, quota exhaustion, symlink
|
|
directories, hard-linked journals and replacement of the root inode. It uses an
|
|
isolated identity database and filesystem. The no-OpenSSL adapter also passed a
|
|
C++17 syntax check.
|
|
|
|
The production web-client test now uses unchanged `uploadTrackFile`,
|
|
`queryTrackUpload` and `discardTrackUpload` through the real management session
|
|
and native TCP worker. Upload/finish/status/abort succeed, cross-session status is
|
|
rejected, and the returned receipt remains `published: false`. The armhf upload,
|
|
management, binary and lifecycle fixtures passed on CM0. This is not a physical
|
|
USB or sudden-power-loss test.
|
|
|
|
On 21 October 2026 the opted-in Linux suite passed 119/119 tests, and Cardputer
|
|
Zero Wayland/framebuffer builds and 14/14 tests passed. Platform boundaries and
|
|
ESP stack hygiene passed. The installed standard CM0 development deb SHA-256 is
|
|
`a830901c2c80cef8a714cccfc43c2f13f9266af21310e56020db9098e786dc8d`.
|
|
Lintian reported no diagnostics; installation and `dpkg -V` passed. The original
|
|
logo and 1232 by 568 P4 render were confirmed. Focused fullscreen Alt+F4 exited
|
|
with code zero in 0.681 seconds. No kernel, display driver, boot configuration or
|
|
network-interface configuration was changed and no reboot was performed.
|
|
|
|
## Remaining work
|
|
|
|
TransferCleanup/ListOwned are now implemented in the separate
|
|
[inventory and cleanup layer](linux-hostlink-upload-maintenance.md).
|
|
Unknown or stale-identity orphan files still consume quota unless exact current
|
|
ownership can be established; they are not silently deleted. Sealing proves
|
|
received bytes only. KML/manifest/package validation,
|
|
retention and atomic route/binding publication are implemented by the separate
|
|
[installation transaction](linux-hostlink-package-install.md), which advertises
|
|
100-101 when available.
|