Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
c6679ce
wip: net
JavierRibaldelRio Oct 18, 2026
7b98b80
wip(backend, net): upload cargo.toml
JavierRibaldelRio Oct 18, 2026
1b388e5
feat(backend, net::tcp): add TCP handles and in-memory framing
pminmic Oct 24, 2026
64dd0bc
feat(backend, net::tcp): TCP connection with single board
pminmic Oct 24, 2026
1ae8c5c
feat(backend, net::tcp): reusable reader using tcp::framing and repor…
pminmic Nov 4, 2026
de39ade
test(backend, net::tcp): manual test to test recieved packets
pminmic Nov 4, 2026
8eadd92
feat(backend, net::tcp): write in the intern tcp buffer and add some …
pminmic Nov 5, 2026
4819713
feat(backend, net::tcp): add configurable TCP keep-alive to session w…
pminmic Nov 5, 2026
2585e81
Merge branch 'new-backend' into backend/net-tcp
pminmic Nov 5, 2026
290d558
feat(backend, net::tcp): selection of the reader/writer for each acti…
pminmic Nov 6, 2026
4da970b
feat(backend, net::tcp): add reconnection supervisor with exponential…
pminmic Nov 9, 2026
194ba14
feat(backend, net::tcp): spawn per-board supervisors
pminmic Nov 9, 2026
f41e562
feat(backend, net::tcp): add prioritized fault boradcast with per-boa…
pminmic Nov 10, 2026
911e39c
tests(backend, net::tcp): add manual test for spawn conections per-bo…
pminmic Nov 10, 2026
d94304c
docs(backend, net::tcp): update README
pminmic Nov 10, 2026
888f4c2
refactor(backend, net::tcp): restrict public API to transport entry p…
pminmic Nov 10, 2026
cfcda70
refactor(backend, tcp): separate tests from tcp.rs file
pminmic Nov 18, 2026
d387cf5
fix(backend, tcp): fixing after pr review (separate tcp tests, change…
pminmic Nov 20, 2026
1ed490b
Merge branch 'new-backend' into backend/net-tcp
pminmic Nov 20, 2026
c21aa0d
fix(backend, tcp): merge conflicts
pminmic Nov 20, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 27 additions & 27 deletions backend/Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

12 changes: 11 additions & 1 deletion backend/crates/core/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,14 @@ serde.workspace = true
serde_json.workspace = true
thiserror.workspace = true
tracing.workspace = true
tokio = { workspace = true, optional = true, features = ["macros", "rt-multi-thread"] }
# `io-util` is what `net` needs on top of the workspace's own list
# (`net`, `sync`, `time`...): `AsyncReadExt`/`AsyncWriteExt`, i.e. reading
# a TCP stream into a buffer at all.
tokio = { workspace = true, optional = true, features = [
"macros",
"rt-multi-thread",
"io-util",
] }
tracing-subscriber = { workspace = true, optional = true , features = ["env-filter", "fmt"]}
tracing-appender = { workspace = true, optional = true }
gix = { version = "0.87.1", optional = true, features = ["blocking-http-transport-reqwest-rust-tls", "blocking-network-client", "worktree-mutation"] }
Expand All @@ -62,6 +69,9 @@ rlimit = { version = "0.11.0", optional = true }
[dev-dependencies]
tempfile = "3.27"

# Virtual time makes the writer's per-frame deadlines deterministic in tests.
tokio = { workspace = true, features = ["test-util"] }

# `workspace = true` can't be combined with extra lints in the same table,
# so the workspace list is repeated here with `missing_docs` added: this is
# the crate meant to be reused by other projects, so its public API must be
Expand Down
14 changes: 10 additions & 4 deletions backend/crates/core/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -8,13 +8,12 @@ pub mod hello_world;
#[cfg(feature = "git")]
pub mod git;

/// NTP server
#[cfg(feature = "ntp")]
pub mod ntp;

/// Basic domain types: identifiers, values, measurements, protections,
/// packets and boards.
pub mod model;
/// NTP server
#[cfg(feature = "ntp")]
pub mod ntp;

/// Parses an ADJ (Architecture Description JSON) directory into
/// [`model::PodData`], plus backend-session metadata not modeled as
Expand All @@ -26,13 +25,20 @@ pub mod adj;
/// [`protocol::tcp`], [`protocol::udp`].
pub mod protocol;

/// Owns the real tokio sockets and reports what arrives on them, calling
/// into [`protocol`] to decode. See [`net::tcp`], [`net::udp`].
#[cfg(feature = "net")]
pub mod net;

// Utils module
pub(crate) mod utils;

/// Everything a recording needs on disk: writing CSV, text and JSON
/// files without knowing what is in them ([`logger::CsvFile`]), moving
/// those files around ([`logger::files`], feature `files`) and the
/// snapshot of the machine that produced them ([`logger::host`],
/// feature `host`). The policy — which files a recording has, what goes
/// in each row — belongs to whoever calls this.

#[cfg(feature = "logger")]
pub mod logger;
46 changes: 46 additions & 0 deletions backend/crates/core/src/net.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
//! Real sockets, on top of tokio (feature `net`).
//!
//! Two submodules do the actual I/O: [`crate::net::tcp`], a client that
//! keeps one task per board and recovers frames out of a byte stream,
//! and [`crate::net::udp`], a single shared receive-only socket. This module opens nothing. It defines only what
//! both of them need to agree on: [`crate::net::Event`] (what happened on
//! a link, carried by a [`crate::net::Notification`]) and
//! [`crate::net::Reporter`] (the two sinks they report through — one for
//! notifications, one for errors).
//!
//! Everything that reaches a [`crate::net::Reporter`] has already been
//! decoded by [`crate::protocol`], which this module layers on top of:
//! `protocol` turns bytes into packets and never touches a socket, `net`
//! owns the socket and calls into it. A sniffer or a simulator can use
//! `protocol` on its own, against a capture, without any of this.
//!
//! # Identity
//!
//! Everything that travels down the notification channel carries its
//! board: [`crate::net::Notification`] holds a
//! [`crate::model::BoardId`] next to the timestamp, whatever the event
//! is. No consumer ever has to go and look up whose packet it just got.
//!
//! It is never a second source of truth, though — it is resolved from
//! what the ADJ already says, once, here. A TCP task was spawned for one
//! board and knows it without asking; [`crate::net::udp`] resolves it
//! from the decoded packet's id through [`crate::protocol::Index`] (every
//! [`crate::model::PacketDef`] carries its `board`), which is one
//! `HashMap` lookup per datagram instead of one per consumer downstream.
//!
//! A board id is all the identity there is: one connection per board, and
//! one shared socket for UDP, so nothing needs telling apart beyond it.
//!
//! Addresses are for the operator, not for the domain types: they show
//! up interpolated in each submodule's error messages (`tcp::Error`,
//! `udp::Error`), which is where somebody actually reads them.

mod error;
mod report;

pub mod tcp;
pub mod udp;

pub use error::Error;
use report::Closed;
pub use report::{ErrorReport, Event, Notification, Reporter, Sinks};
57 changes: 57 additions & 0 deletions backend/crates/core/src/net/README.md
Comment thread
pminmic marked this conversation as resolved.
Resolved
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
# `net` — socket transport (feature `net`)

`net` owns Tokio sockets and uses the synchronous, socket-free `protocol` codecs.
The parent module opens no sockets itself: it exposes transports and defines
their shared reporting types and errors.

Application policy, ADJ loading, logging to disk and frontend integration belong
outside this module. Transport errors and received protections never trigger a
fault automatically; the application decides how to respond.

## Transports

| Module | Status / purpose |
| --- | --- |
| [TCP](tcp/README.md) | A client with one independently reconnecting connection per configured board. Receives messages/protections and writes orders, keep-alive and faults. |
| UDP | Telemetry reception is **not implemented yet**; `udp::spawn` is a placeholder that panics. |

TCP configuration, API usage, guarantees, limitations and manual probes are
documented in [tcp/README.md](tcp/README.md).

## Shared API

| Type / entry point | Purpose |
| --- | --- |
| `Reporter::channels(notifications, errors)` | Create bounded reporting channels and their receiving ends (`Sinks`). Both capacities must be nonzero. |
| `Reporter` | Cloneable reporting handle supplied to transports; publication methods are internal. |
| `Sinks` | Application-owned receivers for notifications and errors. |
| `Notification`, `Event` | Identify a board, timestamp and lifecycle event or decoded packet. |
| `ErrorReport`, `net::Error` | Timestamp transport failures and preserve their transport-specific identity. |

## Reporting

`Notification { board, at, event }` always carries the board's identity alongside
its timestamp. `Event` is `Connected`, `Disconnected` or `Received(Packet)`;
connection lifecycle events are TCP-only. `ErrorReport { at, error }` contains
the failure's own identity through the corresponding `net::Error` variant.
The transport's `Reporter` stamps events when publishing them.

Consume **both** channels concurrently with application operations. Both apply
backpressure rather than dropping on congestion, so leaving either consumer
idle can block publication. There is no ordering guarantee between the two
channels or across independent boards. Cancellation can discard a publication
waiting for capacity; already queued reports remain available to drain.

Closing a consumer is also a transport cancellation signal. The exact shutdown
behavior is transport-specific; see [TCP cancellation](tcp/README.md#reporting-framing-and-cancellation).

## Tests

From `backend/`:

```sh
cargo test -p software-core --features net
```

See [TCP tests and manual probes](tcp/README.md#tests) for hardware requirements,
simulator setup and safety warnings.
28 changes: 28 additions & 0 deletions backend/crates/core/src/net/error.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
//! The one error type an [`super::ErrorReport`] can carry.

use super::{tcp, udp};

/// Anything that went wrong in `net`.
///
/// Aggregation only: this enum adds no identity and no message of its
/// own. Each submodule owns its own error type and puts the identity of
/// whatever failed — the board, or the peer address —
/// *inside* the variant, not just in its text, so that the identity
/// survives being sent down a channel. The Go backend lost it exactly
/// there: the log line before the send had the board, the error value
/// that travelled did not.
///
/// Both variants are `#[error(transparent)]`, so `to_string()` on this
/// enum is the submodule's own message, identity interpolated and all —
/// which is what gets shown to the operator — and `source()` still walks
/// down to the original `io::Error` or
/// [`crate::protocol::DecodeError`].
#[derive(Debug, thiserror::Error)]
pub enum Error {
/// On a board's TCP connection.
#[error(transparent)]
Tcp(#[from] tcp::Error),
/// On the shared UDP socket.
#[error(transparent)]
Udp(#[from] udp::Error),
}
Loading
Loading