Expand description
§carbonfr-sdk
Client Rust asynchrone (tokio) de l’API carbon-fr — intensité carbone de l’électricité française (gCO₂eq/kWh), temps réel et historique.
use carbonfr_sdk::{CarbonFr, IntensityStreamOptions};
use futures_util::StreamExt;
let client = CarbonFr::builder().build()?;
let mut stream = client.intensity_stream(IntensityStreamOptions::default())?;
while let Some(event) = stream.next().await {
println!("{:?}", event?);
}§Couverture
Parité avec les 29 opérations /v1 du SDK TypeScript 0.5.0
(ADR-0031 décision 8 ; health/health_ready, d’exploitation, ne sont pas
exposées) : construction du client (CarbonFr/CarbonFrBuilder),
erreurs typées (CarbonFrError, RFC 9457), 28 méthodes REST (ex.
CarbonFr::intensity_now, CarbonFr::mix, CarbonFr::schedule,
CarbonFr::create_webhook…) et le flux SSE CarbonFr::intensity_stream
(feature Cargo stream). Exemples exécutables dans examples/ du dépôt.
§Construction TLS (ADR-0031 décision 3)
reqwest 0.13 sans provider crypto installé panique à la construction
d’un client. Ce SDK ne s’appuie jamais sur un provider par défaut du
processus (rustls::crypto::CryptoProvider::get_default() /
install_default(), utilisés par bin/server et les adapters de ce
dépôt) : il construit son propre rustls::ClientConfig avec le provider
ring passé explicitement, et le donne à reqwest via
ClientBuilder::tls_backend_preconfigured. Utilisable tel quel dans un
process qui n’installe aucun provider par défaut — voir
client::tests::crypto_provider_default_stays_uninstalled.
Structs§
- Below
Options GET /v1/intensity/below—threshold(requis en pratique, cf. le commentaire de module) est un argument direct decrate::CarbonFr::below.- Carbon
Fr - Client de l’API carbon-fr (intensité carbone de l’électricité française).
- Carbon
FrBuilder - Construit un
CarbonFr. - Cost
Assumptions Body - Hypothèses d’une estimation LCOE (
CostReferenceEntry::hypotheses),None= « non publié par la source », jamais une dimension retirée. - Cost
Reference Entry - Une estimation LCOE (source × technologie × périmètre × millésime,
CostReferenceResponse::entries, ADR-0024). Champs catalogue (technology/source/perimeter/basis) enString: hors du périmètre des enums dupliqués par cette mission. - Cost
Reference Options GET /v1/cost-reference— filtres enString/u32bruts : les valeurs possibles (source,technology,perimeter) ne sont pas dans le périmètre des enums dupliqués par cette mission (sdk-spec.jsonenums_to_duplicate).- Cost
Reference Response - Réponse de
GET /v1/cost-reference— couche comparative LCOE (ADR-0024). Estimation, en fourchette, jamais mise en différence avec le prix de marché (disclaimerobligatoire, ADR-0024 §3). - Create
Webhook Request - Corps de
POST /v1/webhooks(ADR-0016). - Created
Webhook Response - Réponse de création : inclut le secret (affiché une seule fois,
jamais ré-exposé par
GET /v1/webhooks). - Eligibility
Body - Overlay d’éligibilité électrolyseur (
GreenestWindowResponse::eligibility, présent seulement si?eligibility=a été fourni). - Eligibility
Signal Body - Un signal d’un créneau (
EligibilitySlotBody::signals, ADR-0025/0026). - Eligibility
Slot Body - Verdict d’éligibilité d’un créneau (
EligibilityBody::slots). - Eligible
Slot Body - Meilleur créneau éligible (
EligibilityBody::best_eligible). - Exchange
Entry - Une frontière (
ExchangesResponse::exchanges) : flux net signé FR↔voisin - Exchanges
History Response - Réponse de
GET /v1/exchanges/date. - Exchanges
Response - Réponse de
GET /v1/exchanges. - Factor
Entry - Un facteur d’émission par filière (
FactorsResponse::factors). - Factors
Options GET /v1/factors.- Factors
Response - Réponse de
GET /v1/factors. - Forecast
Options GET /v1/intensity/forecast.- Forecast
Point Body - Un point de
GET /v1/intensity/forecast(ForecastResponse::data). - Forecast
Response - Réponse de
GET /v1/intensity/forecast. - Greenest
Window Options GET /v1/intensity/greenest-window.- Greenest
Window Response - Réponse de
GET /v1/intensity/greenest-window. - History
Point - Un point de
GET /v1/intensity/date(HistoryResponse::data). - History
Response - Réponse de
GET /v1/intensity/date. - Index
Band - Une bande du barème de l’index qualitatif (
IntensityIndexResponse::bands), intervalle[min, max[en gCO₂eq/kWh. - Index
Threshold - Une borne du barème et ce qui la fonde (
IntensityIndexResponse::thresholds). - Intensity
AllResponse - Réponse de
GET /v1/intensity/now/all— dernière mesure de chaque région disposant d’une donnée, national puis les 12 régions dans l’ordre deGET /v1/regions(une région sans donnée est omise ; liste vide possible). - Intensity
Date Options GET /v1/intensity/date—from/to(requis) sont des arguments directs decrate::CarbonFr::intensity_date.- Intensity
Index Response - Réponse de
GET /v1/intensity/index— barème de l’index qualitatif (ADR-0033) : même rôle que/v1/factorspour l’ACV, la légende du champindexest auditable (bornes et sources) au lieu d’être codée en dur côté client. Serveur ≥ 0.11 (404 avant). - Intensity
NowAll Options GET /v1/intensity/now/all— pas de région : toutes.- Intensity
NowOptions GET /v1/intensity/now.- Intensity
Response - Réponse de
GET /v1/intensity/now. - Intensity
Stats Options GET /v1/intensity/stats—from/to(requis) sont des arguments directs decrate::CarbonFr::intensity_stats.- Intensity
Value - Valeur d’intensité carbone (
IntensityResponse::intensity). - Lcoe
Range Body - Fourchette d’une estimation LCOE (
CostReferenceEntry::range). - Marginal
Technology Body - Technologie marginale estimée (
PriceContextBody::marginal_technology, ordre de mérite domestique — jamais mesurée,estimatedvaut toujourstrue). - Methodologies
Response - Réponse de
GET /v1/methodologies. - Methodology
Info - Une méthodologie du catalogue (
MethodologiesResponse::methodologies). - MixBody
- Mix de production par filière (
MixResponse::mix), en MW. - MixOptions
GET /v1/mix.- MixResponse
- Réponse de
GET /v1/mix. - MixShare
Body - Part d’une filière dans la production (
MixResponse::shares). Même forme quePriceMixShareBody(contexte de/v1/price, un seul composant OpenAPI côté serveur) — type distinct pour ne pas changer celui d’un champ public déjà publié. - Price
Component Body - Une composante du prix (
PriceResponse::components). - Price
Context Body - Contexte explicatif du prix (
PriceResponse::context, ADR-0023 §4). - Price
History Options GET /v1/price/date—from/to(requis) sont des arguments directs decrate::CarbonFr::price_history;region, si fourni, doit être national (même remarque quePriceOptions).- Price
History Response - Réponse de
GET /v1/price/date. - Price
MixShare Body - Part d’une filière dans le mix (
PriceContextBody::mix). - Price
Options GET /v1/price—region, si fourni, doit être national (toute autre valeur renvoie 400, le TRV est national) : documenté ici comme côté SDK TS, pas imposé par un type dédié (le serveur reste la source de vérité).- Price
Point Body - Un point compact de
GET /v1/price/date(PriceHistoryResponse::points). - Price
Response - Réponse de
GET /v1/price. - Problem
Details - Corps Problem Details (RFC 9457) porté par
CarbonFrError::Api. - Region
Info - Une région servie (
RegionsResponse::regions). - Regions
Response - Réponse de
GET /v1/regions— catalogue statique : national puis les 12 régions métropolitaines (même ordre queGET /v1/intensity/now/all). - Renewable
Model Info - Capacités effectives calibrées (
RenewableResponse::model, transparence du modèle). - Renewable
Response - Réponse de
GET /v1/renewable. - Ruleset
Info - Une entrée du catalogue (
RulesetsResponse::rulesets). - Rulesets
Response - Réponse de
GET /v1/eligibility/rulesets. - Savings
Body - Économie carbone d’un créneau planifié vs « maintenant » (ADR-0014).
- Schedule
Options GET /v1/schedule.- Schedule
Response - Réponse de
GET /v1/schedule. - Schedule
Slots Options GET /v1/schedule/slots—count(requis en pratique, cf. le commentaire de module) est un argument direct decrate::CarbonFr::schedule_slots.- Slot
Body - Un créneau (
GET /v1/schedule/slots,GET /v1/intensity/below). - Slots
Response - Réponse d’une liste de créneaux (
GET /v1/schedule/slots,GET /v1/intensity/below). - Stats
Bucket - Un seau agrégé de
GET /v1/intensity/stats?interval=(StatsResponse::intervals). - Stats
Response - Réponse de
GET /v1/intensity/stats. - Visit
Stats Response - Réponse de
GET /v1/statsetPOST /v1/stats/visit. - Weather
History Response - Réponse de
GET /v1/weather/date. - Weather
Point - Un créneau météo (
WeatherHistoryResponse::points), vent à 100 m + irradiance, moyenne nationale. - Weather
Response - Réponse de
GET /v1/weather. - Webhook
List Response - Réponse de
GET /v1/webhooks. - Webhook
Summary - Résumé d’un abonnement, sans le secret (
WebhookListResponse::webhooks).
Enums§
- Carbon
FrError - Erreur du SDK carbon-fr.
- Eligibility
Framework - Cadre d’éligibilité électrolyseur (ADR-0025/0026) :
rfnbo(Règl. délégués UE 2023/1184-1185) oulow-carbon(Acte délégué UE 2025/2359). Deux piliers du droit européen tel qu’adopté ; une révision réglementaire (rfnbo:2026-revision,planned) reste une version du même cadre (RulesetInfo::version), pas un 3ᵉ cadre. - Eligibility
Signal Provenance - Provenance de la valeur d’un signal d’éligibilité
(
EligibilitySignalBody::provenance, absente sur un signalindeterminate) :observed(donnée mesurée/publiée) ouforecast(prévision,share-clim@1). Ouverte (#[non_exhaustive]+EligibilitySignalProvenance::Other, commecrate::Region) :sdk-spec.jsonla marqueopen: true, contrairement aux autres enums de ce fichier. - Eligibility
Signal Verdict - Verdict d’un signal d’éligibilité (
EligibilitySignalBody::verdict, ADR-0025/0026) :pass,failouindeterminate(donnée manquante, jamais extrapolée). - Estimator
- Estimateur d’intensité prévue (ADR-0009/0011) :
central(estimation) ouprudent(borne haute de l’intervalle de confiance). - Flow
Direction - Sens d’un flux transfrontalier (
ExchangeEntry/ExchangesResponse, ADR-0017) — champ de réponse uniquement, jamais un paramètre de requête :import(> 0),export(< 0) oubalanced. - Intensity
Index - Index qualitatif d’une intensité carbone (ADR-0033, barème
index@1) : cinq bandes absolues en gCO₂eq/kWh, séparées par les bornes 20 · 64,8 · 100 · 200 — basses incluses, hautes exclues ([a, b[: 20 g estlow, 19,9 g estvery-low). Un seul barème pour toutes les méthodologies et toutes les régions ; le catalogue des bornes et de leurs sources est servi parGET /v1/intensity/index(CarbonFr::intensity_index). - Interval
- Pas d’agrégation d’une série (
GET /v1/intensity/stats?interval=) :hourouday. - Methodology
- Méthodologie de calcul de l’intensité carbone (ADR-0005) :
rte-direct(national, taux CO₂ publié directement) ouacv-ademe(cycle de vie, national + 12 régions). Catalogue fini : une nouvelle méthodologie est un changement de méthodologie, donc un nouvel ADR (CONTRIBUTING.md) — exhaustif, pas#[non_exhaustive](ADR-0030 §3). - Region
- Région éCO2mix : national ou l’une des 12 régions métropolitaines, ou tout autre slug accepté/renvoyé par le serveur mais pas encore listé ici.
- Threshold
Direction - Sens de franchissement d’un seuil (webhooks, ADR-0016) — paramètre de
requête et champ de réponse (
CreateWebhookRequest/WebhookSummary) :belowouabove. - Webhook
Status - État d’un abonnement webhook (
WebhookSummary::status, ADR-0016) :active, oudisabled(désactivé automatiquement après une série de livraisons échouées — le réactiver suppose de le supprimer puis le recréer, nouveau secret).
Constants§
- DEFAULT_
BASE_ URL - URL de base de l’instance hébergée par défaut (ADR-0031).
- DEFAULT_
CONNECT_ TIMEOUT - Délai par défaut d’établissement de connexion (cf.
CarbonFrBuilder::connect_timeout) : pour le REST, TCP + TLS seulement (le reste de la requête relève deDEFAULT_TIMEOUT) ; pour le flux SSE, TCP + TLS + envoi de la requête + réception des en-têtes, le flux n’ayant ensuite aucun timeout total (ADR-0031, points tranchés 2026-09-25). - DEFAULT_
TIMEOUT - Délai par défaut d’une requête REST (connexion + réponse) — écart assumé à
la parité stricte avec le SDK TS, qui n’en a aucun (point tranché par
Morgan le 2026-09-25, ADR-0031). Configurable
(
CarbonFrBuilder::timeout) et désactivable (CarbonFrBuilder::no_timeout).