From 5ad4f60958183ed7d7fcd52aa2932c36cc533e40 Mon Sep 17 00:00:00 2001 From: Justin Kovacich Date: Fri, 11 Sep 2026 10:31:37 -0400 Subject: [PATCH 1/5] docs: add health files and complete the crate metadata simple-someip is the most-downloaded crate in the org and had the thinnest packaging: no keywords, no categories, no homepage, no documentation link, and no readme field, so it surfaces poorly in crates.io search relative to how much it is used. It also had no disclosure path, no conduct policy, and no contributing guide. SECURITY.md is written for SOME/IP specifically. The distinction worth stating is that E2E Profile 4/5 are safety mechanisms: a CRC is unkeyed, so anyone who can alter a payload can recompute it, and E2E protection does not make a channel tamper-resistant. Service discovery is likewise unauthenticated by design. Decode robustness - particularly bounds handling in the fixed-capacity heapless SD collections - is the part that is in scope. CONTRIBUTING.md documents the feature graph, which is the easiest thing to get wrong here, and the fact that most integration tests declare required-features so a bare `cargo test` silently skips them. `rust-version` is deliberately still absent: main.yml says choosing an MSRV is a policy decision, so this records that rather than settling it. Co-Authored-By: Claude Opus 5 (1M context) --- .github/CODEOWNERS | 3 ++ CODE_OF_CONDUCT.md | 129 +++++++++++++++++++++++++++++++++++++++++++++ CONTRIBUTING.md | 97 ++++++++++++++++++++++++++++++++++ Cargo.toml | 8 +++ README.md | 3 ++ SECURITY.md | 50 ++++++++++++++++++ 6 files changed, 290 insertions(+) create mode 100644 .github/CODEOWNERS create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md create mode 100644 SECURITY.md diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..e02adda --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,3 @@ +# Default owners for everything in the repo. Review routing only — the +# main-branch ruleset does not currently require code-owner approval. +* @luminartech/luv diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..a81db8a --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,129 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, caste, color, religion, or sexual +identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +- Demonstrating empathy and kindness toward other people +- Being respectful of differing opinions, viewpoints, and experiences +- Giving and gracefully accepting constructive feedback +- Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +- Focusing on what is best not just for us as individuals, but for the overall + community + +Examples of unacceptable behavior include: + +- The use of sexualized language or imagery, and sexual attention or advances of + any kind +- Trolling, insulting or derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information, such as a physical or email address, + without their explicit permission +- Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official email address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement at +. All complaints will be reviewed and investigated +promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series of +actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or permanent +ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within the +community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.1, available at +. + +Community Impact Guidelines were inspired by +[Mozilla's code of conduct enforcement ladder][mozilla]. + +For answers to common questions about this code of conduct, see the FAQ at +. Translations are available at +. + +[homepage]: https://www.contributor-covenant.org +[mozilla]: https://github.com/mozilla/inclusion diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..6622209 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,97 @@ +# Contributing + +Pull requests are welcome, as are bug reports and questions in the issue +tracker. + +The crate implements the +[Open SOME/IP Specification](https://github.com/some-ip-com/open-someip-spec). +`README.md` describes the module layout; this document covers the parts of the +build that are easy to get wrong. + +## The feature graph + +`default = ["std"]`, and the feature set is the most intricate thing about this +crate. The client and server each split into a trait surface and a tokio +convenience layer: + +- `client` / `server` — the executor-agnostic trait surface. No tokio, no + socket2. Callers supply their own `Spawner`, `Timer`, `ChannelFactory` and + `TransportFactory`. +- `client-tokio` / `server-tokio` — the same, plus the tokio defaults that make + `Client::new` and `Server::new` work. Both force `std`. +- `bare_metal` — activates embassy-sync as the channel backend along with + `static_channels`, `AtomicInterfaceHandle` and `StaticE2EHandle`. Enabling it + alone does **not** make the crate bare-metal-complete: `client` and `server` + still need user-provided `Spawner` and `TransportFactory` impls. +- `bare-metal-runtime` — the composed embassy runtime on top of that. +- `embassy_channels` — heap-backed channel backend, useful before static pools + are sized. +- `_alloc` — private marker for "this build needs `extern crate alloc`". It is + tied to the declaration in `lib.rs` so both sides move together. Do not + enable it directly. + +`tracing` is feature-gated rather than always-on because `tracing-core` declares +`extern crate alloc` unconditionally, which bare-metal targets shipping a +`core`-only sysroot cannot satisfy. + +## Testing + +Most integration tests declare `required-features`, so a bare `cargo test` +silently skips them. Run the configurations, not just the default: + +```sh +cargo test --features client-tokio,server-tokio # the async engines +cargo test --features client,bare_metal # the bare-metal client +cargo test --features server,bare_metal # the bare-metal server +cargo test --all-features +``` + +Two tests are allocation witnesses (`no_alloc_witness`, +`no_alloc_server_witness`) and run with `harness = false`: they fail if the +no-alloc paths start allocating. Treat a change that trips one as a design +question, not a test to adjust. + +The bare-metal examples are workspace members and exercise the real +configuration rather than a feature flag on the root crate: + +```sh +cargo build -p bare_metal_client +cargo build -p bare_metal_server +``` + +`tests/wire_golden.rs` pins the bytes on the wire. A round-trip test written +against the crate's own output passes whenever encode and decode share the same +misreading, so a wire-format change should either fail a golden vector or add +one. + +## Minimum supported Rust version + +The manifest deliberately declares no `rust-version`, and CI's MSRV job is +switched off as a result. Picking a floor is a policy decision about what the +project commits to supporting — if you need one, raise it as an issue rather +than adding it as a side effect of another change. + +## Commits and pull requests + +Commit subjects follow [Conventional Commits](https://www.conventionalcommits.org/) +(`feat:`, `fix:`, `docs:`, `build:`, `chore:`, with a `!` for a breaking +change), because the changelog is organized around them. + +`Linear PR History` is a required check: rebase onto `main` rather than merging +`main` into your branch. + +## Continuous integration + +Two pipelines currently run side by side: this repository's own workflow, which +produces `Format & Lint`, `Build, Test & Coverage`, the Windows and +bare-metal/no_std builds and `SemVer Check`; and the org-wide reusable workflow +from [`luminartech/rust_workflow`](https://github.com/luminartech/rust_workflow), +which produces the `ci / *` checks. The three required checks come from the +former. + +## Releases + +[release-plz](https://release-plz.dev) owns versioning, the changelog, tags, +GitHub releases, and the crates.io publish. There is no version to bump by +hand: a push to `main` maintains an open release PR, and merging that PR +publishes. diff --git a/Cargo.toml b/Cargo.toml index a04f266..c4585f5 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -29,6 +29,14 @@ edition = "2024" license = "MIT OR Apache-2.0" description = "A lightweight SOME/IP serialization and communication library" repository = "https://github.com/luminartech/simple_someip" +homepage = "https://github.com/luminartech/simple_someip" +documentation = "https://docs.rs/simple-someip" +readme = "README.md" +keywords = ["someip", "automotive", "no-std", "embedded", "serialization"] +categories = ["network-programming", "embedded", "no-std", "encoding"] +# No `rust-version` on purpose: choosing an MSRV is a support-policy +# decision, not a packaging one. CI's MSRV job stays off until one is +# chosen deliberately (see .github/workflows/main.yml). [dependencies] crc = "3.4" diff --git a/README.md b/README.md index cf0221b..a359110 100644 --- a/README.md +++ b/README.md @@ -3,6 +3,9 @@ [![CI](https://img.shields.io/github/actions/workflow/status/luminartech/simple_someip/ci.yml?style=for-the-badge&label=CI)](https://github.com/luminartech/simple_someip/actions/workflows/ci.yml) [![Coverage](https://img.shields.io/codecov/c/github/luminartech/simple_someip?style=for-the-badge)](https://app.codecov.io/gh/luminartech/simple_someip) [![Crates.io](https://img.shields.io/crates/v/simple-someip?style=for-the-badge)](https://crates.io/crates/simple-someip) +[![Docs.rs](https://img.shields.io/docsrs/simple-someip?style=for-the-badge)](https://docs.rs/simple-someip) +[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg?style=for-the-badge)](./LICENSE-MIT) +[![APACHE License](https://img.shields.io/badge/license-APACHE-blue.svg?style=for-the-badge)](./LICENSE-APACHE) Simple SOME/IP is a Rust library implementing the SOME/IP automotive communication protocol — remote procedure calls, event notifications, and wire format serialization. Based on the [Open SOME/IP Specification](https://github.com/some-ip-com/open-someip-spec). diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..4986a1b --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,50 @@ +# Security policy + +## Reporting a vulnerability + +Report security issues through GitHub's private vulnerability reporting: open +the [Security tab](https://github.com/luminartech/simple_someip/security) and +choose **Report a vulnerability**. That opens a private advisory visible only +to the maintainers. + +Please do not open a public issue for a security report. + +A report is most useful with the crate version, the feature set enabled, and a +byte sequence or test case that reproduces the behavior. + +## Supported versions + +This crate is pre-1.0. Fixes land on the latest published version; there are no +maintained release branches. + +## Scope + +`simple-someip` implements the SOME/IP wire format, service discovery, and the +client and server engines above them. Three properties of SOME/IP matter when +assessing a report, because they are the protocol's design rather than defects +in this crate: + +- **SOME/IP carries no transport security.** Messages travel as plaintext UDP + or TCP. There is no confidentiality, and nothing in the protocol binds a + message to a sender. Reading or injecting traffic on a network that carries + SOME/IP is the protocol working as specified; protecting that network is the + integrator's job. +- **Service discovery is unauthenticated.** An SD offer asserts that a service + lives at an endpoint, and nothing in the protocol lets a client verify that + assertion. A host able to send SD messages on the segment can offer a service + it does not own and draw subscriptions to itself. This crate encodes and + decodes SD entries; it cannot tell a legitimate offer from a spoofed one. +- **E2E protection is a safety mechanism, not a security one.** Profile 4 + (CRC-32) and Profile 5 (CRC-16) detect accidental corruption — bit flips, + truncation, a stale or duplicated frame. A CRC is not a message + authentication code: it is unkeyed, so anyone who can alter a payload can + recompute the checksum over it. E2E protection does not make a channel + tamper-resistant, and a report that it can be forged describes the profile + rather than a bug here. + +What is in scope: anything that makes the crate misbehave on attacker-supplied +bytes — a panic, an out-of-bounds read, an unbounded allocation, a decode that +accepts a frame it should reject, or a hang reachable from the wire. The +fixed-capacity `heapless` collections used by the SD codec make +bounds-handling on oversized or malformed entries a particular area of +interest. From 978707427a67a24bf8743a7e1bcf8954c0a1d155 Mon Sep 17 00:00:00 2001 From: Justin Kovacich Date: Fri, 11 Sep 2026 12:44:28 -0400 Subject: [PATCH 2/5] docs: draw the feature graph instead of describing it The feature section spent a paragraph and six bullets describing which feature pulls in which, which is exactly the part a reader can absorb faster as a picture. A mermaid graph now carries the edges - GitHub renders it inline - and the prose keeps only what a diagram cannot say: that client/server are the executor-agnostic trait surface, that bare_metal alone is not bare-metal complete, that _alloc is private, and why tracing is gated. The 11 edges were checked against the [features] table programmatically rather than transcribed by eye. Co-Authored-By: Claude Opus 5 (1M context) --- CONTRIBUTING.md | 61 ++++++++++++++++++++++++++++++------------------- 1 file changed, 38 insertions(+), 23 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6622209..550ec47 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,29 +10,44 @@ build that are easy to get wrong. ## The feature graph -`default = ["std"]`, and the feature set is the most intricate thing about this -crate. The client and server each split into a trait surface and a tokio -convenience layer: - -- `client` / `server` — the executor-agnostic trait surface. No tokio, no - socket2. Callers supply their own `Spawner`, `Timer`, `ChannelFactory` and - `TransportFactory`. -- `client-tokio` / `server-tokio` — the same, plus the tokio defaults that make - `Client::new` and `Server::new` work. Both force `std`. -- `bare_metal` — activates embassy-sync as the channel backend along with - `static_channels`, `AtomicInterfaceHandle` and `StaticE2EHandle`. Enabling it - alone does **not** make the crate bare-metal-complete: `client` and `server` - still need user-provided `Spawner` and `TransportFactory` impls. -- `bare-metal-runtime` — the composed embassy runtime on top of that. -- `embassy_channels` — heap-backed channel backend, useful before static pools - are sized. -- `_alloc` — private marker for "this build needs `extern crate alloc`". It is - tied to the declaration in `lib.rs` so both sides move together. Do not - enable it directly. - -`tracing` is feature-gated rather than always-on because `tracing-core` declares -`extern crate alloc` unconditionally, which bare-metal targets shipping a -`core`-only sysroot cannot satisfy. +`default = ["std"]`. An arrow means *enables*: + +```mermaid +flowchart TD + F_default(["default"]) --> F_std["std"] + F_std --> F_tracing["tracing"] + F_std --> F_alloc["_alloc"] + + F_ctokio["client-tokio"] --> F_client["client"] + F_ctokio --> F_std + F_stokio["server-tokio"] --> F_server["server"] + F_stokio --> F_std + + F_bmr["bare-metal-runtime"] --> F_bm["bare_metal"] + F_bmr --> F_server + F_ec["embassy_channels"] --> F_bm + F_ec --> F_alloc +``` + +The arrows are the mechanical part. These are the things the graph cannot tell +you: + +- **`client` / `server` are the executor-agnostic trait surface** — no tokio, no + socket2. You supply `Spawner`, `Timer`, `ChannelFactory` and + `TransportFactory`. The `-tokio` variants add the defaults that make + `Client::new` and `Server::new` work, and force `std`. +- **`bare_metal` alone is not bare-metal-complete.** It activates embassy-sync as + the channel backend along with `static_channels`, `AtomicInterfaceHandle` and + `StaticE2EHandle` — but `client` and `server` still need your own `Spawner` and + `TransportFactory` impls. +- **`_alloc` is private; do not enable it directly.** It marks "this build needs + `extern crate alloc`" and is tied to the declaration in `lib.rs` so both sides + move in lockstep. +- **`tracing` is gated rather than always-on** because `tracing-core` declares + `extern crate alloc` unconditionally, which bare-metal targets shipping a + `core`-only sysroot cannot satisfy. +- **`embassy_channels` is the heap-backed channel backend** — useful for tests or + early prototypes, before static pools are sized. ## Testing From cca2adda09d8dd7e59ba33abc8c0fb2982c96cec Mon Sep 17 00:00:00 2001 From: Justin Kovacich Date: Fri, 11 Sep 2026 12:48:55 -0400 Subject: [PATCH 3/5] docs: drop the editorialising above the feature-graph notes Co-Authored-By: Claude Opus 5 (1M context) --- CONTRIBUTING.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 550ec47..38328d3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -29,8 +29,7 @@ flowchart TD F_ec --> F_alloc ``` -The arrows are the mechanical part. These are the things the graph cannot tell -you: +What the graph doesn't show: - **`client` / `server` are the executor-agnostic trait surface** — no tokio, no socket2. You supply `Spawner`, `Timer`, `ChannelFactory` and From cae9d90e020bf9ca12d25089b6edff383e4adbe9 Mon Sep 17 00:00:00 2001 From: Justin Kovacich Date: Fri, 11 Sep 2026 12:51:44 -0400 Subject: [PATCH 4/5] docs: drop default from the feature graph default is the default feature set rather than a feature like the others, and the line above the diagram already states default = ["std"], so the node was both odd and redundant. Co-Authored-By: Claude Opus 5 (1M context) --- CONTRIBUTING.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 38328d3..b08b7ce 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,12 +10,11 @@ build that are easy to get wrong. ## The feature graph -`default = ["std"]`. An arrow means *enables*: +`default = ["std"]`. Among the features themselves, an arrow means *enables*: ```mermaid flowchart TD - F_default(["default"]) --> F_std["std"] - F_std --> F_tracing["tracing"] + F_std["std"] --> F_tracing["tracing"] F_std --> F_alloc["_alloc"] F_ctokio["client-tokio"] --> F_client["client"] From 3490b7f393852ea18a868374c7d0f78276771de1 Mon Sep 17 00:00:00 2001 From: Justin Kovacich Date: Fri, 11 Sep 2026 12:54:31 -0400 Subject: [PATCH 5/5] docs: correct the feature graph and drop the --all-features line Three corrections found by reading lib.rs rather than the manifest alone. `#![no_std]` is unconditional - `std` is the feature that adds std back via `extern crate std`, not a switch that turns no_std on. The section implied the opposite by omission, and there is no no_std node to add: the axis is already the `std` node. `bare-metal-runtime` pulls `server` and not `client`, so there is no bare-metal client edge to draw. The bare-metal client path is `client` + `bare_metal` with a caller-supplied executor. Saying so avoids the diagram reading as though the client case were missing. `cargo test --all-features` was wrong and is removed: `--all-features` enables `bare-metal-runtime` alongside `std` and trips the `compile_error!` in lib.rs. Verified - it fails to compile. The graph now carries that exclusivity as a dashed link, and the nightly requirement for `impl_trait_in_assoc_type` is noted alongside it. The four remaining test commands were each checked to compile, and the ten enables edges re-checked against the [features] table. Co-Authored-By: Claude Opus 5 (1M context) --- CONTRIBUTING.md | 25 ++++++++++++++++++++++--- 1 file changed, 22 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b08b7ce..d42ebc7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,12 +10,17 @@ build that are easy to get wrong. ## The feature graph -`default = ["std"]`. Among the features themselves, an arrow means *enables*: +`#![no_std]` is unconditional: `std` is the feature that adds `std` back, not a +switch that turns `no_std` on. `default = ["std"]`. + +A solid arrow means *enables*; the dashed link marks a pair that refuses to +compile. `_alloc` is double-bordered because it is private — every other node +is a feature you are meant to turn on. ```mermaid flowchart TD F_std["std"] --> F_tracing["tracing"] - F_std --> F_alloc["_alloc"] + F_std --> F_alloc[["_alloc"]] F_ctokio["client-tokio"] --> F_client["client"] F_ctokio --> F_std @@ -26,6 +31,8 @@ flowchart TD F_bmr --> F_server F_ec["embassy_channels"] --> F_bm F_ec --> F_alloc + + F_bmr -. "cannot combine" .- F_alloc ``` What the graph doesn't show: @@ -38,6 +45,15 @@ What the graph doesn't show: the channel backend along with `static_channels`, `AtomicInterfaceHandle` and `StaticE2EHandle` — but `client` and `server` still need your own `Spawner` and `TransportFactory` impls. +- **`bare-metal-runtime` is server-side only.** It pulls in `server`, not + `client` — it composes the embassy executor and the single task around the + server. A bare-metal *client* is `client` + `bare_metal` with an executor you + supply; see `examples/bare_metal_client/`. +- **`bare-metal-runtime` cannot be combined with the alloc features.** A + `compile_error!` rejects it alongside `_alloc`, and therefore alongside `std`, + `embassy_channels` and both `*-tokio` features. It also needs nightly, for + `impl_trait_in_assoc_type`. Build it alone: + `cargo +nightly check --no-default-features --features bare-metal-runtime,server`. - **`_alloc` is private; do not enable it directly.** It marks "this build needs `extern crate alloc`" and is tied to the declaration in `lib.rs` so both sides move in lockstep. @@ -56,9 +72,12 @@ silently skips them. Run the configurations, not just the default: cargo test --features client-tokio,server-tokio # the async engines cargo test --features client,bare_metal # the bare-metal client cargo test --features server,bare_metal # the bare-metal server -cargo test --all-features +cargo test --no-default-features # the no_std core alone ``` +There is deliberately no `--all-features` line: it enables +`bare-metal-runtime` alongside `std` and hits the `compile_error!` above. + Two tests are allocation witnesses (`no_alloc_witness`, `no_alloc_server_witness`) and run with `harness = false`: they fail if the no-alloc paths start allocating. Treat a change that trips one as a design