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..d42ebc7 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,129 @@ +# 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 + +`#![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_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 + + F_bmr -. "cannot combine" .- F_alloc +``` + +What the graph doesn't show: + +- **`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. +- **`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. +- **`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 + +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 --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 +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.