Skip to main content

Crate flare_server_core

Crate flare_server_core 

Source
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_base provides context, errors, configuration, IDs, and shared service types.
  • flare_core_runtime provides service lifecycle, task orchestration, health checks, shutdown signals, and state tracking.
  • flare_core_infra provides KV, authentication, metrics, and telemetry helpers.
  • flare_core_transport provides HTTP, gRPC, service discovery, and transport middleware.
  • flare_core_messaging provides 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 to flare-proto structured 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§

AuthenticatedPrincipal
ClientContextConfig
客户端上下文拦截器配置
ClientContextInterceptor
客户端上下文拦截器:自动为所有请求添加/合并 Context 并编码到 metadata。
CompositeTokenValidator
主 TokenService + 可选额外 issuer,用于 IM 长连接等多来源 JWT 校验。
Config
Context
上下文:主链路元数据 + 取消/超时 + 父子 + TypeMap。
ContextLayer
Context 中间件层
ContextService
DiscoveryFactory
服务发现工厂
EventEnvelope
统一事件信封:事件总线上的标准载荷(与具体业务解耦)
InMemoryEventBus
内存版事件总线(单机 CQRS / 模块解耦)
InMemoryTopicEventBus
内存 Topic 总线:同进程多订阅者;不跨进程、不持久化
KvStore
KV存储实现
LoggingSubscriberOptions
与典型 YAML/TOML 日志段对齐的 fmt 层选项(不依赖任何应用配置类型)
MeshConfig
MqEventHandler
将 EventHandler 适配为 crate::mq::consumer::MessageHandler
OtlpTracingOptions
OTLP trace exporter 配置。
RegistryConfig
ServerConfig
ServiceClient
服务发现客户端
ServiceConfig
ServiceDiscover
实现 tower::discover::Discover 的服务发现器
ServiceRuntime
服务运行时
StorageConfig
TokenClaims
JWT claims used for access tokens
TokenService
Stateless token service backed by HMAC (HS256)
TokenValidationRequest
TopicBroadcast
一次 Topic 发布的快照(订阅方 recv 得到;可按 topic 过滤)
TrustedIssuer
额外信任的 JWT 发行方(如 Social 登录签发的 access_token)。

Enums§

AuthError
ErrorCode
错误代码枚举 - 用于国际化
FlareError
Flare IM 统一错误类型
LoadBalanceStrategy
负载均衡策略

Constants§

DEFAULT_TOPIC_BROADCAST_CAPACITY
默认广播槽位(慢消费者易 Lagged,生产可酌情调大)
EVENT_ENVELOPE_CONTENT_TYPE
与 crate::mq::consumer::ContentType::Json 的 MIME 一致,写入 Kafka/NATS 等消息头
HEADER_CONTENT_TYPE
标准消息头键(小写,与 KafkaProducer 等一致)

Traits§

EventBus
统一事件总线接口
EventSubscriber
事件订阅者接口
KvBackend
KV存储后端 trait
TokenValidator
TopicEventBus
基于 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:log crate 事件经 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。

Type Aliases§

MqTopicEventBus