flare-server-core 1.1.1

Server-side infrastructure toolkit for Flare IM services: runtime, transport, messaging, auth, telemetry, and context propagation.
Documentation

Flare Server Core

English · 中文

⚠ Clone this next to its sibling repos

This crate depends on flare-proto by path, at ../flare-proto. Cloning this repository on its own does not build — cargo metadata fails before it reaches your code, with an error naming an internal workspace member that tells you nothing about the real cause.

mkdir flare && cd flare
git clone https://github.com/flare-im/flare-proto.git
git clone https://github.com/flare152/flare-server-core.git
cd flare-server-core && cargo check

ℹ 这是通信基础设施,不是开箱即用的 IM 产品

说在前面,免得你 clone 完才发现登不上去:开源部分不含账号体系 (没有注册登录、好友关系、群角色/审批/禁言、朋友圈)。

但它自带完整且可插拔的鉴权契约,两条路都在开源侧:

  • CoreJwtTokenValidator —— 本地验 JWT。手签一个 token 就能跑起来做 demo / POC,不需要任何用户体系。
  • HttpHookTokenValidator —— 把 token POST 到你自己的接口, 这是接入自有用户体系的入口。

业务规则同理:flare-im-core/crates/flare-im-hooks 提供 9 个扩展点 (PreSend / PostSend / Delivery / Recall / MessageRead / MessageReaction / ConversationLifecycle / ConversationMember / GetConversationParticipants)。

要上生产,你需要自行实现用户体系并按上述契约接入 —— 与 Sendbird / Twilio Conversations 的「自带身份」模型一致,区别是 Flare 可自托管、 协议与核心可审计。

边界详情见 GOVERNANCE.md。

Crates.io Documentation License: Apache-2.0 Rust

flare-server-core is the server-side infrastructure toolkit used by Flare IM services. It packages reusable runtime, transport, messaging, authentication, context propagation, service discovery, telemetry, and error-handling building blocks into a small set of composable crates.

The package is business-neutral: it does not own IM product rules, inbox sync policy, moderation, or tenant-specific workflows. Those belong in application services and higher-level domain crates.

API documentation: docs.rs/flare-server-core

Installation

[dependencies]
flare-server-core = "1.0.1"

Feature-focused examples:

# HTTP + auth + telemetry
flare-server-core = { version = "1.0.1", features = ["http", "auth", "telemetry"] }

# gRPC service with discovery
flare-server-core = { version = "1.0.1", features = ["grpc", "discovery"] }

# Eventing and MQ integrations
flare-server-core = { version = "1.0.1", features = ["nats", "kafka"] }

# Everything
flare-server-core = { version = "1.0.1", features = ["full"] }

The workspace also publishes the lower-level crates with the same version:

Crate Purpose
flare-core-base Context, errors, configuration, IDs, and shared types.
flare-core-runtime Service lifecycle, task orchestration, health, shutdown, and state tracking.
flare-core-infra KV, token validation, auth helpers, and telemetry setup.
flare-core-transport HTTP, gRPC, service discovery, and transport middleware.
flare-core-messaging Event bus, topic bus, NATS, Kafka, producers, consumers, and retry helpers.
flare-server-core Aggregated re-export crate for server applications.

All of them use version 1.0.1 so application teams can keep dependency versions aligned.

Feature Flags

Feature Description
http Axum HTTP helpers, response models, and middleware.
grpc Tonic gRPC client/server context utilities and middleware.
discovery Service discovery and client-side service selection.
nats NATS JetStream producer/consumer support.
kafka Kafka producer/consumer support.
kv Infrastructure KV abstractions.
auth Token validation, principal model, and composite validators.
telemetry Tracing subscriber and OpenTelemetry helpers.
proto Optional bridge to flare-proto structured payloads.
full Enables all public server-core capabilities.

Architecture

Application service
      |
flare-server-core        re-export layer for service code
      |
+-------------------+---------------------+--------------------+
| flare-core-base   | flare-core-runtime  | flare-core-infra   |
| context/errors/id | lifecycle/tasks     | auth/kv/telemetry  |
+-------------------+---------------------+--------------------+
      |
+------------------------+------------------------+
| flare-core-transport   | flare-core-messaging   |
| HTTP/gRPC/discovery    | eventbus/MQ/NATS/Kafka |
+------------------------+------------------------+

Runtime Example

use flare_server_core::ServiceRuntime;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    ServiceRuntime::new("gateway")
        .with_address("0.0.0.0:8080".parse()?)
        .add_spawn("worker", async { Ok(()) })
        .run()
        .await?;

    Ok(())
}

Context And Errors

use flare_server_core::{Context, ErrorBuilder, ErrorCode, Result};

fn require_tenant(ctx: &Context) -> Result<&str> {
    ctx.tenant_id().ok_or_else(|| {
        ErrorBuilder::new(ErrorCode::ConfigurationError, "tenant is required").build_error()
    })
}

Release Verification

For package-level checks:

cargo test --workspace --all-features
RUSTDOCFLAGS="-D warnings" cargo doc --workspace --all-features --no-deps
cargo package -p flare-server-core

When publishing the full workspace, publish dependency crates first:

  1. flare-core-base
  2. flare-core-runtime
  3. flare-core-infra
  4. flare-core-transport
  5. flare-core-messaging
  6. flare-server-core

License

Licensed under the Apache License, Version 2.0.


下一步

想做什么 去哪里
五分钟跑起来 QUICKSTART —— 起服务、手签 token、调通接口,不需要自建用户体系
接入自己的用户系统 实现 TokenValidator(CoreJwtTokenValidator 本地验签 / HttpHookTokenValidator 调你的接口)
加自己的业务规则 flare-im-hooks 的 9 个扩展点:PreSend / PostSend / Delivery / Recall / MessageRead / MessageReaction / ConversationLifecycle / ConversationMember / GetConversationParticipants
做界面 @flare-im/vue-ui —— 107 个组件,四端一致的契约
报安全问题 SECURITY.md,请勿开公开 issue

需要账号体系与社交能力时

开源部分是通信基础设施。如果你需要的是现成的账号、好友关系、群治理(角色 / 入群审批 / 禁言)、朋友圈, 这些在商业模块里 —— 自研这一层通常要数月,且都是与通信无关的重复劳动。

企业场景另有 SSO / 组织架构 / 审计导出 / 数据驻留 / SLA 支持。

咨询:flare1522@163.com

边界划分与不变承诺见 GOVERNANCE。 简言之:已开源的不会被收回,鉴权与 hooks 契约永远开源、不会为逼迫付费而阉割。