Skip to main content

flare_server_core/
lib.rs

1//! Aggregated server-side infrastructure toolkit for Flare services.
2//!
3//! `flare-server-core` re-exports the lower-level server infrastructure crates
4//! under one dependency for application services that want a compact import
5//! surface. It covers runtime lifecycle, context propagation, typed errors,
6//! HTTP/gRPC helpers, service discovery, event buses, message queues,
7//! authentication, KV abstractions, and telemetry setup.
8//!
9//! # Crate Layout
10//!
11//! - [`flare_core_base`] provides context, errors, configuration, IDs, and
12//!   shared service types.
13//! - [`flare_core_runtime`] provides service lifecycle, task orchestration,
14//!   health checks, shutdown signals, and state tracking.
15//! - [`flare_core_infra`] provides KV, authentication, metrics, and telemetry
16//!   helpers.
17//! - [`flare_core_transport`] provides HTTP, gRPC, service discovery, and
18//!   transport middleware.
19//! - [`flare_core_messaging`] provides event-bus, topic-bus, NATS, and Kafka
20//!   primitives.
21//!
22//! # Feature Flags
23//!
24//! Enable only the integration surfaces you need:
25//!
26//! - `http`: HTTP response and middleware helpers.
27//! - `grpc`: tonic context, client, interceptor, and middleware helpers.
28//! - `discovery`: service discovery and service clients.
29//! - `nats` / `kafka`: MQ integrations.
30//! - `kv`, `auth`, `telemetry`: infrastructure adapters.
31//! - `proto`: optional bridge to `flare-proto` structured payloads.
32//! - `full`: all public capabilities.
33
34// Re-export all lower-level crates.
35pub use flare_core_base;
36pub use flare_core_infra;
37pub use flare_core_messaging;
38pub use flare_core_runtime;
39pub use flare_core_transport;
40
41// Common module re-exports.
42pub use flare_core_base::config;
43pub use flare_core_base::context;
44pub use flare_core_base::error;
45pub use flare_core_base::types;
46
47// Utility module. With `grpc`, this also includes gRPC context helpers.
48#[cfg(not(feature = "grpc"))]
49pub use flare_core_base::utils;
50
51#[cfg(feature = "grpc")]
52pub mod utils {
53    // Base utilities.
54    pub use flare_core_base::utils::*;
55    // gRPC utilities.
56    pub use flare_core_transport::grpc::utils::{
57        extract_ctx_from_request_opt, require_ctx_from_request,
58    };
59}
60
61// Error types and macros.
62pub use flare_core_base::error::{ErrorCode, FlareError};
63
64// Error macros.
65pub use flare_core_base::{flare_err, flare_err_details};
66
67// Context type.
68pub use flare_core_base::context::Context;
69
70// Configuration types.
71pub use flare_core_base::config::{
72    Config, MeshConfig, RegistryConfig, ServerConfig, ServiceConfig, StorageConfig,
73};
74
75// gRPC utilities.
76#[cfg(feature = "grpc")]
77pub use flare_core_transport::grpc::utils::{
78    extract_ctx_from_request_opt, require_ctx_from_request,
79};
80
81// gRPC client helpers.
82#[cfg(feature = "grpc")]
83pub use flare_core_transport::grpc::client::{
84    ClientContextConfig, ClientContextInterceptor, context_interceptor_with_tenant,
85    context_interceptor_with_tenant_and_user, default_context_interceptor, request_with_context,
86    set_context_metadata,
87};
88
89// gRPC middleware helpers.
90#[cfg(feature = "grpc")]
91pub use flare_core_transport::grpc::middleware::{
92    ContextLayer, ContextService, extract_actor_id, extract_context, extract_request_id,
93    extract_tenant_id, extract_user_id, get_context, require_actor_id, require_request_id,
94    require_tenant_id, require_user_id,
95};
96
97// Transport modules.
98#[cfg(feature = "http")]
99pub use flare_core_transport::http;
100
101#[cfg(feature = "grpc")]
102pub use flare_core_transport::grpc;
103
104#[cfg(feature = "discovery")]
105pub use flare_core_transport::discovery;
106
107// Service discovery types.
108#[cfg(feature = "discovery")]
109pub use flare_core_transport::discovery::{DiscoveryFactory, LoadBalanceStrategy, ServiceDiscover};
110
111// Messaging layer.
112pub use flare_core_messaging::eventbus;
113pub use flare_core_messaging::mq;
114
115// NATS JetStream support.
116#[cfg(feature = "nats")]
117pub use flare_core_messaging::mq::nats;
118
119// Common event-bus types.
120pub use flare_core_messaging::eventbus::{
121    DEFAULT_TOPIC_BROADCAST_CAPACITY, EVENT_ENVELOPE_CONTENT_TYPE, EventBus, EventEnvelope,
122    EventSubscriber, HEADER_CONTENT_TYPE, InMemoryEventBus, InMemoryTopicEventBus, MqEventHandler,
123    MqTopicEventBus, TopicBroadcast, TopicEventBus, register_event_handler, run_event_consumer,
124};
125
126// Infrastructure modules.
127pub use flare_core_infra::auth;
128pub use flare_core_infra::kv;
129pub use flare_core_infra::telemetry;
130
131// Authentication types.
132pub use flare_core_infra::auth::{
133    AuthError, AuthenticatedPrincipal, CompositeTokenValidator, TokenClaims, TokenService,
134    TokenValidationRequest, TokenValidator, TrustedIssuer,
135};
136
137// KV storage types.
138pub use flare_core_infra::kv::{KvBackend, KvStore};
139
140// Common telemetry types.
141pub use flare_core_infra::telemetry::{
142    LoggingSubscriberOptions, OtlpTracingOptions, init_fmt_subscriber, init_tracing_subscriber,
143};
144
145// Runtime types.
146pub use flare_core_runtime::ServiceRuntime;
147pub use flare_core_runtime::config as runtime_config;
148pub use flare_core_runtime::task;
149
150// Runtime module.
151pub use flare_core_runtime as runtime;
152
153// Service discovery client.
154#[cfg(feature = "discovery")]
155pub use flare_core_transport::discovery::ServiceClient;
156
157// Middleware module.
158#[cfg(all(feature = "http", not(feature = "grpc")))]
159pub use flare_core_transport::http::middleware;
160
161#[cfg(all(feature = "grpc", not(feature = "http")))]
162pub mod middleware {
163    pub use flare_core_transport::grpc::middleware::{
164        ContextLayer, ContextService, extract_actor_id, extract_context, extract_request_id,
165        extract_tenant_id, extract_user_id, get_context, require_actor_id, require_request_id,
166        require_tenant_id, require_user_id,
167    };
168}
169
170#[cfg(all(feature = "http", feature = "grpc"))]
171pub mod middleware {
172    // HTTP middleware.
173    pub use flare_core_transport::http::middleware::*;
174    // gRPC middleware.
175    pub use flare_core_transport::grpc::middleware::{
176        ContextLayer, ContextService, extract_actor_id, extract_context, extract_request_id,
177        extract_tenant_id, extract_user_id, get_context, require_actor_id, require_request_id,
178        require_tenant_id, require_user_id,
179    };
180}
181
182// gRPC client module.
183#[cfg(feature = "grpc")]
184pub mod client {
185    pub use flare_core_transport::grpc::client::{
186        ClientContextConfig, ClientContextInterceptor, context_interceptor_with_tenant,
187        context_interceptor_with_tenant_and_user, default_context_interceptor,
188        request_with_context, set_context_metadata,
189    };
190}
191
192// Discovery client module.
193#[cfg(feature = "discovery")]
194pub mod discovery_client {
195    pub use flare_core_transport::discovery::ServiceClient;
196}