carbonfr-core 0.9.4

Domain, use cases and ports for carbon-fr's carbon-intensity core — pure, IO-free Rust (hexagonal architecture).
Documentation

carbonfr-core

Domain, use cases and ports for carbon-fr, the open API for the carbon intensity of French electricity (gCO₂eq/kWh, based on RTE/éCO2mix open data via ODRÉ).

crates.io docs.rs MSRV 1.88

What this crate is

carbonfr-core is the hexagonal-architecture core of carbon-fr: domain types (carbon intensity, measurements, generation mix, forecasts, cost/price references, cross-border flows, webhooks…), use cases, and the ports (async_trait traits) that adapters implement. It is pure: no I/O, no HTTP client, no SQL, no async runtime — only computation over plain Rust types. Adapters (HTTP, PostgreSQL, ODRÉ, ENTSO-E…) and the composition root live in separate, unpublished crates of the same workspace.

Minimal example

use carbonfr_core::domain::{CarbonIntensity, Measurement, Methodology, Region, Vintage};
use time::OffsetDateTime;

let intensity = CarbonIntensity::new(42.0).expect("finite, non-negative value");
let measurement = Measurement {
    at: OffsetDateTime::now_utc(),
    region: Region::National,
    intensity,
    methodology: Methodology::rte_direct(),
    vintage: Vintage::Tr,
    mix: None,
};
assert_eq!(measurement.region, Region::National);

This snippet compiles against this crate as-is (manually verified against the crate; not wired into cargo test doctests as this README isn't included via #[doc = include_str!(...)]).

Third-party types on the public API

Kept and documented rather than hidden behind newtypes (ADR-0030 §3):

  • time — OffsetDateTime for every timestamp in the domain (Measurement::at, forecast points, webhook scheduling…), Duration for spans and freshness bounds (MAX_FLOW_CONTEXT_AGE, MAX_SPOT_STALENESS, ClimatologyParams::{step, tau}, HorizonBands, BackfillHistory::new) and Date for day-level values (VisitStats::since). A consumer of this crate depends on time for these types.
  • async-trait — every port in ports is #[async_trait]. Implementing a port from outside this crate (a custom adapter) requires the same macro, or hand-desugaring to Pin<Box<dyn Future>>.

Out of scope

This crate never touches, and never will:

  • I/O of any kind — HTTP, SQL, filesystem, network. That's the adapters' job (separate, unpublished crates of the carbon-fr workspace).
  • SQL migrations — live in crates/adapter-postgres/migrations/ in the main repository, not here.
  • /hydrogene map data (ADR-0029) — a static dataset served by bin/server, unrelated to this crate's domain.
  • Adapters and the composition root (bin/server) — never published; they're coupled to axum/sqlx/reqwest and the deployment shape.

MSRV

Rust 1.88.0, set by a direct dependency (time), not by the 2024 edition alone. Raising the MSRV is a minor version bump (see below), never a patch, and only when a direct dependency requires it.

SemVer policy (pre-1.0)

This crate is 0.x: per ADR-0030 §3, a breaking change (removing/renaming a public item, adding a variant to an exhaustive enum, adding a field to a struct with public fields) is a minor bump (0.x → 0.(x+1)), never a patch.

Public enums are classified one by one, not with a blanket rule:

  • #[non_exhaustive] on enums that are open-ended catalogs expected to grow with the domain, the data, or the surrounding infrastructure (the five error enums, ApiTier, Perimeter, CostSource, CostTechnology, CostBasis, PriceComponentKind, Filiere, Neighbor).
  • Exhaustive where the set is finite by construction of the domain (Vintage, ThresholdDirection, Region, Granularity, WindowEstimator) — extending one of these would itself be a methodology change requiring a new ADR, so there's nothing to protect against under SemVer.

Structs with public fields (the vast majority of the domain's data types: Measurement, GenerationMix, ForecastPoint…) keep their fields public and are never retrofitted with #[non_exhaustive]: they're plain data, meant to be constructed by literal by downstream consumers (including the future Rust SDK, ADR-0031). Adding a public field to one of them is a minor bump too.

No optional features exist yet (in particular, no serde feature before 1.0 — see ADR-0030 §6): adding one later is additive under SemVer, so there's no reason to reserve it in advance.

License

Dual-licensed under MIT or Apache-2.0, at your option.

Links