Expand description
Aggregated server-side infrastructure toolkit for Flare services.
flare-server-core re-exports the lower-level server infrastructure crates
under one dependency for application services that want a compact import
surface. It covers runtime lifecycle, context propagation, typed errors,
HTTP/gRPC helpers, service discovery, event buses, message queues,
authentication, KV abstractions, and telemetry setup.
§Crate Layout
flare_core_baseprovides context, errors, configuration, IDs, and shared service types.flare_core_runtimeprovides service lifecycle, task orchestration, health checks, shutdown signals, and state tracking.flare_core_infraprovides KV, authentication, metrics, and telemetry helpers.flare_core_transportprovides HTTP, gRPC, service discovery, and transport middleware.flare_core_messagingprovides event-bus, topic-bus, NATS, and Kafka primitives.
§Feature Flags
Enable only the integration surfaces you need:
http: HTTP response and middleware helpers.grpc: tonic context, client, interceptor, and middleware helpers.discovery: service discovery and service clients.nats/kafka: MQ integrations.kv,auth,telemetry: infrastructure adapters.proto: optional bridge toflare-protostructured payloads.full: all public capabilities.
Re-exports§
pub use flare_core_base;pub use flare_core_infra;pub use flare_core_messaging;pub use flare_core_runtime;pub use flare_core_transport;pub use flare_core_runtime as runtime;
Modules§
- auth
- client
- config
- context
- 上下文模块(极简、0 拷贝)
- discovery
- 统一服务发现与负载均衡模块
- discovery_
client - error
- Flare Server Core 错误处理模块
- eventbus
- Event bus primitives.
- grpc
- gRPC 模块
- http
- HTTP 模块
- kv
- KV存储抽象模块
- middleware
- mq
- 统一的消息队列抽象层
- nats
- NATS JetStream 实现模块
- runtime_
config - 运行时配置模块
- task
- 任务抽象模块
- telemetry
- 进程级日志与 trace 订阅器初始化(
tracing-subscriber+tracing-log+ 可选 OTLP),与具体业务配置解耦。 - types
- utils
Macros§
- flare_
err - 快速构造
FlareError(仅 code + reason)。 - flare_
err_ details - 构造带
details的FlareError。
Structs§
- Authenticated
Principal - Client
Context Config - 客户端上下文拦截器配置
- Client
Context Interceptor - 客户端上下文拦截器:自动为所有请求添加/合并 Context 并编码到 metadata。
- Composite
Token Validator - 主 TokenService + 可选额外 issuer,用于 IM 长连接等多来源 JWT 校验。
- Config
- Context
- 上下文:主链路元数据 + 取消/超时 + 父子 + TypeMap。
- Context
Layer - Context 中间件层
- Context
Service - Discovery
Factory - 服务发现工厂
- Event
Envelope - 统一事件信封:事件总线上的标准载荷(与具体业务解耦)
- InMemory
Event Bus - 内存版事件总线(单机 CQRS / 模块解耦)
- InMemory
Topic Event Bus - 内存 Topic 总线:同进程多订阅者;不跨进程、不持久化
- KvStore
- KV存储实现
- Logging
Subscriber Options - 与典型 YAML/TOML 日志段对齐的 fmt 层选项(不依赖任何应用配置类型)
- Mesh
Config - MqEvent
Handler - 将 EventHandler 适配为 crate::mq::consumer::MessageHandler
- Otlp
Tracing Options - OTLP trace exporter 配置。
- Registry
Config - Server
Config - Service
Client - 服务发现客户端
- Service
Config - Service
Discover - 实现 tower::discover::Discover 的服务发现器
- Service
Runtime - 服务运行时
- Storage
Config - Token
Claims - JWT claims used for access tokens
- Token
Service - Stateless token service backed by HMAC (HS256)
- Token
Validation Request - Topic
Broadcast - 一次 Topic 发布的快照(订阅方
recv得到;可按topic过滤) - Trusted
Issuer - 额外信任的 JWT 发行方(如 Social 登录签发的 access_token)。
Enums§
- Auth
Error - Error
Code - 错误代码枚举 - 用于国际化
- Flare
Error - Flare IM 统一错误类型
- Load
Balance Strategy - 负载均衡策略
Constants§
- DEFAULT_
TOPIC_ BROADCAST_ CAPACITY - 默认广播槽位(慢消费者易
Lagged,生产可酌情调大) - EVENT_
ENVELOPE_ CONTENT_ TYPE - 与 crate::mq::consumer::ContentType::Json 的 MIME 一致,写入 Kafka/NATS 等消息头
- HEADER_
CONTENT_ TYPE - 标准消息头键(小写,与
KafkaProducer等一致)
Traits§
- Event
Bus - 统一事件总线接口
- Event
Subscriber - 事件订阅者接口
- KvBackend
- KV存储后端 trait
- Token
Validator - Topic
Event Bus - 基于 Topic 的事件总线(内存或 MQ);错误统一为
flare_core_base::error::FlareError
Functions§
- context_
interceptor_ with_ tenant - 创建带默认 tenant_id 的拦截器
- context_
interceptor_ with_ tenant_ and_ user - 创建带默认 tenant_id 和 user_id 的拦截器
- default_
context_ interceptor - 创建带默认配置的拦截器
- extract_
actor_ id - actor_id(来自 Context 的 actor)
- extract_
context - 从请求扩展中取出 Context
- extract_
ctx_ from_ request_ opt - 从 gRPC Request 提取 Ctx(可选版本)
- extract_
request_ id - request_id
- extract_
tenant_ id - 租户 ID
- extract_
user_ id - 用户 ID(user_id 或 actor.actor_id)
- get_
context - 从请求中取 Ctx 引用(避免 clone)
- init_
fmt_ subscriber - 安装全局 fmt subscriber:
logcrate 事件经tracing-log汇入同一流。 - init_
tracing_ subscriber - 安装全局 tracing subscriber,可选启用 OTLP trace exporter。
- register_
event_ handler - 注册事件处理器到指定主题
- request_
with_ context - 创建并设置 Context 到 metadata 的 gRPC 请求。
- require_
actor_ id - require_
ctx_ from_ request - 从 gRPC Request 提取 Ctx(必需版本)
- require_
request_ id - require_
tenant_ id - require_
user_ id - run_
event_ consumer - 运行事件消费者
- set_
context_ metadata - 将 Context 编码到 gRPC 请求的 metadata。