kanarpc

package module
v0.0.0-...-3f998ea Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 6, 2026 License: AGPL-3.0 Imports: 28 Imported by: 0

README

KanaRPC

KanaRPC 是一个 Go RPC 框架,在过载时限制请求接纳,为并发调用分配有界资源,并跟踪取消与停机时的交付结果。 支持普通调用、服务端流式调用、JSON / Protobuf 和 TCP/TLS / 原生 QUIC。

本地演示 · 业务接入 · 压测与验证 · 架构与协议

核心设计

问题 实现 证据
慢方法积压时怎样限制新请求 服务端按方法加权调度,用有界队列限制等待,按处理器耗时通过 AIMD 调整执行并发。客户端用短效反馈在编码前接纳或拒绝 过载对照实验
请求数有限,怎样约束并发编码和未读数据 连接和连接池有字节预算,流式发送受信用窗口限制。未读流、进行中的解码和退休连接持有的缓冲继续计入预算,直至释放 池级预算与故障测试
停机时怎样知道哪些请求已经收尾 统一排队、远端取消、终态回执和资源释放。DrainWithReport 分别报告资源是否退出和协议交付故障,业务提交由应用确认 关闭与故障注入

快速体验

需要 Go 1.26.10+,推荐 Go 1.27.3 或所在分支的最新安全补丁。在仓库根目录运行:

go run ./cmd/showcase

打开 127.0.0.1:8080,通过三组操作观察一次请求如何经过框架。

  1. 制造过载。调整请求速率、慢请求比例和后端槽位,观察并发上限、排队与客户端提前拒绝。
  2. 取消流式请求。收到片段后取消,沿时间线核对取消信号、处理器返回和资源释放。
  3. 执行优雅关闭。注入一次终态未回执故障,分别查看资源退出和交付结果。

控制台使用本机 QUIC 和可调的模拟负载,启动无需 etcd、容器或 npm。操作指南 · 界面截图(注入未回执故障) · 链路验证

业务接入

CampusTrace 的 Worker 通过 KanaRPC 调用岗位分析服务,使用 TCP 普通调用、etcd 服务发现、连接复用、固定执行上限和远端取消。业务重试与写入回执由 CampusTrace 管理。接入设计与验收

接进你的项目

模块路径为 github.com/KanaDoodle/KanaRPC。处理器显式接收 context.Context:

server, err := kanarpc.NewServer(kanarpc.ServerConfig{})
// 检查 err 后注册方法。
err = kanarpc.RegisterUnary(server, "/math/add", func(ctx context.Context, in [2]int) (int, error) {
    return in[0] + in[1], ctx.Err()
})
// 检查 err,创建 net.Listener,再调用 server.Serve(listener)。
// 客户端:
// client, err := kanarpc.Dial(ctx, address, kanarpc.ClientConfig{})
// err = client.Call(ctx, "/math/add", [2]int{1, 2}, &sum)

这是注册与调用片段;完整可运行示例见 连接管理 和 关闭报告。服务端流使用 RegisterStream,客户端通过 Stream/Recv 消费结果,提前结束时调用 Close。版本选择与独立消费模块的接入方式见 开发说明。

运行 go run ./cmd/protobuf-demo 可体验生成 SDK 的普通调用、流式接收与远端取消。.proto 定义、代码生成和连接池接入见 Protobuf 使用指南,让类型帮你记住方法和参数 (•̀ᴗ•́)و

准备接进独立应用时,按 SDK 治理与发布 固定版本、检查生成代码和 schema 兼容性。历史验收证据保留在仓库中,Go 模块下载包专注 SDK 源码与使用文档。

跑通业务接入链

go run ./cmd/production-demo
# 也可以选择 -transport tls 或 -transport quic。

示例在本机完成鉴权、类型化请求、流式响应、压缩、追踪和关闭。接入选项、临时证书和调试 CLI 见完整调用链。

架构与调用链

根包负责请求状态机、编解码、传输适配和资源治理;discovery 提供 etcd 注册与快照;routing 消费发现快照并管理连接。QUIC 传输基于 quic-go,注册发现基于 etcd client。

一次请求会走过这条路线:业务管线与凭证 → 路由 / 限流 / 总 deadline → 客户端接纳与编码预留 → 编码与按需压缩 → 服务端接纳与方法调度 → 鉴权 / 解压 / 执行 / 信用流控 → END 与协议回执 → 请求退休与资源释放。取消、截止时间和连接故障通过同一状态机参与终态结算。编码准备、排队、执行、回执等待与未读数据分别统计,便于定位压力来源。

文档 内容
架构与演进、KNR2 协议 模块职责、请求状态与帧契约
业务接入与完整调用链 元数据、中间件、鉴权、gzip、观测、就绪发布和调用策略
Protobuf 与 Go SDK、组件评估 接口定义、二进制负载、生成代码与依赖升级
传输与发现、连接管理 TLS/QUIC、etcd 一致性与连接归属
过载治理、控制回退 调度、延迟目标、压力反馈与复位
编码前接纳、共享预算 字节租约、未读流与退休对象统计
关闭与故障计数、使用约束 取消、回执、关闭结果与部署要求
网络诊断、QUIC 发送、小请求分析 根因、内部基线和优化取舍

压测与验证

验证场景 结果
过载与恢复 在本机容量切换实验中,相比仅服务端自适应,加入客户端反馈后按时完成数增加 13.4%,成功总数下降 3.6%。提前拒绝部分请求,减少等待。实验与退化样本
TCP 流式优化 R14 本机双进程、并发 16、每次 8 × 1 KiB 的流式调用,内核优化后吞吐由 18,226 升至 24,695 RPC/s,P95 由 1.21 ms 降至 0.85 ms,均为四轮中位数。相同条件下 grpc-go 吞吐为 74,306 RPC/s。同条件对照
后续调用管线回归 R15 默认路径复测中,TCP 短流吞吐相对 R14 的配对变化中位数为 −9.76%。完整结果
GOWORK=off go build -mod=readonly ./...
GOWORK=off go test ./...
GOWORK=off go test -race ./...

etcd 集成用例需要独立实例,可通过 开发说明 中的 runner 自动创建和回收。各阶段的环境、源码快照、完整请求结果、失败与退化数据保存在 验证索引。已有测量来自本机 loopback 与本地 Linux VM;真实双机、WAN、多成员 etcd 和模型推理性能尚未验证。

普通与流式调用的 TCP/TLS 外部基线见 grpc-go 同条件对照,包含完整矩阵、CPU/分配开销及不利结果。后续的 profile 定位、信用合并与 TCP writev 记录见 并发与流式优化。

兼容性与许可

KNR2 v2 使用独立的协议和运行内核,与旧 KanaRPC-Go wire protocol 分离。接入时显式选择端点与传输;业务幂等、方法鉴权及重试策略由应用管理。其他资源、取消和回执契约统一见 使用约束。

项目采用 AGPL-3.0。实现沿革、旧项目关系和第三方依赖记录见 ORIGINS.md。

Documentation

Overview

Package kanarpc implements context-first unary and server-streaming RPC. The v2 experimental protocol is intentionally incompatible with KanaRPC-Go.

Index

Examples

Constants

View Source
const MaxMetadataBytes = 4096
View Source
const SupportPackageIsVersion1 = true

SupportPackageIsVersion1 is the compile-time contract required by generated bindings. Supported generation APIs remain available across compatible SDKs.

Variables

View Source
var (
	ErrClosed   = errors.New("kanarpc: closed")
	ErrDraining = errors.New("kanarpc: draining")
	ErrProtocol = errors.New("kanarpc: peer violated protocol")
	ErrDelivery = errors.New("kanarpc: terminal receipt not acknowledged")
)
View Source
var ErrCapabilities = errors.New("kanarpc: required protocol capabilities unavailable")

Functions

func CaptureTrailers

func CaptureTrailers(ctx context.Context, capture *MetadataCapture) context.Context

func DrainReceiver

func DrainReceiver(s Receiver) error

DrainReceiver consumes a stream to its protocol terminal without decoding.

func RegisterHealth

func RegisterHealth(s *Server) error

RegisterHealth exposes JSON health Check/Watch over the same authenticated transport and optional authentication policy. State is application-controlled.

func RegisterIntrospection

func RegisterIntrospection(s *Server) error

RegisterIntrospection is opt-in and uses the same authentication middleware. It publishes method names/shapes, not a gRPC reflection service.

func RegisterProtobufMethods

func RegisterProtobufMethods(s *Server, bindings ...ProtobufMethod) error

RegisterProtobufMethods installs a service atomically before Serve. Invalid or duplicate bindings leave the server unchanged.

func RegisterProtobufStream

func RegisterProtobufStream[Request, Response proto.Message](s *Server, path string, newRequest func() Request, handler func(context.Context, Request, func(Response) error) error) error

func RegisterProtobufUnary

func RegisterProtobufUnary[Request, Response proto.Message](s *Server, path string, newRequest func() Request, handler func(context.Context, Request) (Response, error)) error

func RegisterStream

func RegisterStream[Request, Response any](s *Server, path string, h func(context.Context, Request, func(Response) error) error) error

func RegisterUnary

func RegisterUnary[Request, Response any](s *Server, path string, h func(context.Context, Request) (Response, error)) error

RegisterUnary provides compile-time request/response types without reflection.

func SetTrailer

func SetTrailer(ctx context.Context, metadata Metadata) error

func WithOutgoingMetadata

func WithOutgoingMetadata(ctx context.Context, m Metadata) context.Context

WithOutgoingMetadata copies m; validation happens before request encoding.

Types

type AdmissionStats

type AdmissionStats struct {
	Limit, Active, Preparing, Encoding, Peak int
	EncodingWaiters                          int
	Rejected                                 uint64
	Closed                                   bool
}

AdmissionStats includes accepted preparation, wire calls and owned cleanup. Finished unread stream buffers are accounted separately by MemoryStats.

type Authenticator

type Authenticator func(context.Context, CallInfo) (Identity, error)

Authenticator validates credentials from IncomingMetadata. It executes in the bounded request worker, before decompression and application decoding.

type BudgetError

type BudgetError struct {
	Class, Scope           string
	Requested, Used, Limit int64
	// contains filtered or unexported fields
}

BudgetError identifies a local framework reservation refusal. Across the wire only Status is transmitted: a remote ResourceExhausted or reset does not establish which budget (or whether a budget) refused the peer. Scope is owner, pool_class, pool_data, or closed_owner. Used is the usage used for this decision (zero for an impossible absolute-size reservation).

func (*BudgetError) Error

func (e *BudgetError) Error() string

func (*BudgetError) Unwrap

func (e *BudgetError) Unwrap() error

type BufferStats

type BufferStats struct {
	Streams, Chunks         int
	Bytes                   int64
	PeakStreams, PeakChunks int
	PeakBytes               int64
}

type BufferUsage

type BufferUsage struct {
	Streams, Chunks int
	Bytes           int64
}

type ByteStats

type ByteStats struct {
	Limit, Used, Peak int64
	Rejected          uint64
}

type CallInfo

type CallInfo struct {
	Method, Side string
	Streaming    bool
	Started      time.Time
	QueueWait    time.Duration
}

type CallResult

type CallResult struct {
	CallInfo
	Err      error
	Duration time.Duration
	Attempts int
}

type Caller

type Caller interface {
	Call(context.Context, string, any, any) error
	Stream(context.Context, string, any) (*Stream, error)
	Close()
}

func DialEndpoint

func DialEndpoint(ctx context.Context, endpoint Endpoint, options DialOptions) (Caller, error)

type Capabilities

type Capabilities struct {
	Negotiated    bool
	Features      Feature
	MaxFrameBytes uint32
}

type CapabilityError

type CapabilityError struct {
	Required, Supported Feature
	Cause               error
}

CapabilityError precedes business dispatch. It never authorizes a retry of another call. Cause preserves cancellation, deadlines and handshake failures.

func (*CapabilityError) Error

func (e *CapabilityError) Error() string

func (*CapabilityError) Unwrap

func (e *CapabilityError) Unwrap() error

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client owns a single multiplexed byte-stream connection. There is no implicit reconnect, business retry, registry worker, or background heartbeat.

func Dial

func Dial(ctx context.Context, address string, cfg ClientConfig) (*Client, error)

func DialTLS

func DialTLS(ctx context.Context, address string, options TLSOptions, cfg ClientConfig) (*Client, error)

func NewClient

func NewClient(conn net.Conn, cfg ClientConfig) (*Client, error)

NewClient transfers conn ownership on success only. It also accepts a caller-authenticated TLS connection; TLS construction is not automated here. RequiredFeatures performs bounded network IO before returning. On failure the caller still owns conn and must close it; negotiation may have written.

func (*Client) AdmissionStats

func (c *Client) AdmissionStats() AdmissionStats

func (*Client) BufferStats

func (c *Client) BufferStats() BufferStats

func (*Client) Call

func (c *Client) Call(ctx context.Context, method string, request, response any) error

func (*Client) Capabilities

func (c *Client) Capabilities() Capabilities

func (*Client) Close

func (c *Client) Close()

func (*Client) CompressionStats

func (c *Client) CompressionStats() CompressionStats

func (*Client) FeedbackStats

func (c *Client) FeedbackStats() FeedbackStats

func (*Client) MemoryStats

func (c *Client) MemoryStats() MemoryStats

func (*Client) OpenStream

func (c *Client) OpenStream(ctx context.Context, method string, request any) (Receiver, error)

func (*Client) Stats

func (c *Client) Stats() ClientStats

func (*Client) Stream

func (c *Client) Stream(ctx context.Context, method string, request any) (*Stream, error)

Stream begins one server-streaming call. Caller cancellation is always sent on the wire. Call and Stream share the same request/terminal state machine.

func (*Client) WaitIdle

func (c *Client) WaitIdle(ctx context.Context) error

WaitIdle waits for accepted calls/preparation/cleanup, not the idle reader or completed unread buffers. Close first to seal admission. User encoders cannot be forcibly interrupted; no detached encoding goroutine is created.

type ClientConfig

type ClientConfig struct {
	EnableCallOptions bool
	Compression       *CompressionConfig
	TCPKeepAlive      *TCPKeepAliveConfig
	// RequiredFeatures enables a bounded pre-dispatch handshake. Zero preserves
	// legacy JSON connections. Protobuf calls require FeatureProtobuf here.
	RequiredFeatures Feature

	// MemoryAccount is an optional single-owner share of a MemoryPool.
	MemoryAccount  *MemoryAccount
	Feedback       *FeedbackConfig
	Memory         MemoryConfig
	IO             IOConfig
	Timeout        time.Duration
	MaxInFlight    int
	StreamWindow   int
	ControlTimeout time.Duration
	// contains filtered or unexported fields
}

type ClientPipeline

type ClientPipeline struct {
	// contains filtered or unexported fields
}

ClientPipeline is the single production call entry for direct clients and routing.Client alike; generated SDKs consume this same ServiceCaller.

func NewClientPipeline

func NewClientPipeline(inner ServiceCaller, cfg PipelineConfig) (*ClientPipeline, error)

func (*ClientPipeline) AdmissionStats

func (p *ClientPipeline) AdmissionStats() AdmissionStats

func (*ClientPipeline) Call

func (p *ClientPipeline) Call(ctx context.Context, method string, request, response any) (err error)

func (*ClientPipeline) Close

func (p *ClientPipeline) Close()

func (*ClientPipeline) OpenStream

func (p *ClientPipeline) OpenStream(ctx context.Context, method string, request any) (result Receiver, err error)

func (*ClientPipeline) Wait

func (p *ClientPipeline) Wait(ctx context.Context) error

Wait joins protocol completions/interceptors. After Close it also joins an owned routing caller's Wait, including application-held stream leases.

type ClientStats

type ClientStats struct {
	Pending, InFlightBufferedChunks          int
	Started, Completed, Canceled, LateFrames uint64
	DecodeErrors                             uint64
}

type Code

type Code string
const (
	OK                 Code = "ok"
	Canceled           Code = "canceled"
	DeadlineExceeded   Code = "deadline_exceeded"
	ResourceExhausted  Code = "resource_exhausted"
	Unavailable        Code = "unavailable"
	InvalidArgument    Code = "invalid_argument"
	Internal           Code = "internal"
	NotFound           Code = "not_found"
	Unauthenticated    Code = "unauthenticated"
	PermissionDenied   Code = "permission_denied"
	FailedPrecondition Code = "failed_precondition"
)

func StatusCode

func StatusCode(err error) Code

StatusCode returns the sanitized framework classification for instrumentation.

type Completion

type Completion interface {
	Done() <-chan struct{}
	Outcome() error
}

Completion exposes protocol termination separately from unread buffer ownership.

type CompressionConfig

type CompressionConfig struct{ MinBytes int }

CompressionConfig enables gzip negotiation. Small/unprofitable messages stay plain. Workspace reservations are additional to payload reservations.

type CompressionStats

type CompressionStats struct{ Prepared, GzipPrepared, PlainBytes, EncodedBodyBytes, DecodedGzip, InflatedBytes uint64 }

CompressionStats measures prepared business bodies, not successful delivery, TCP/TLS/QUIC overhead, or application consumption. Counters are cumulative.

type ControlDecision

type ControlDecision struct {
	Method, Reason         string
	Previous, Next         int
	P90                    time.Duration
	PreviousMode, NextMode ControlMode
	Generation             uint64
}

type ControlMode

type ControlMode string
const (
	ControlStatic   ControlMode = "static"
	ControlAdaptive ControlMode = "adaptive"
	ControlFallback ControlMode = "fixed_fallback"
)

type DeliveryFaults

type DeliveryFaults struct{ LostTerminals, IncompleteExchanges uint64 }

type DialOptions

type DialOptions struct {
	Client ClientConfig
	TLS    TLSOptions
	QUIC   QUICConfig
}

type DrainReport

type DrainReport struct {
	Before, After             ServerStats
	MemoryBefore, MemoryAfter MemoryStats
	PriorFaults, AddedFaults  DeliveryFaults
	TotalFaults               DeliveryFaults
	Quiescent                 bool
}

DrainReport separates resource completion from cumulative delivery health. Before is captured under the admission lock when this drain seals admission. Quiescent joins framework readers and handlers, not external application work or remote consumption/commit. Memory snapshots use their own budget locks; they are not atomic with the RPC counters. No history is reset by drain.

type Endpoint

type Endpoint struct {
	ID        string    `json:"id"`
	Address   string    `json:"address"`
	Transport Transport `json:"transport"`
}

func (Endpoint) Validate

func (e Endpoint) Validate() error

type Feature

type Feature uint32
const (
	FeatureProtobuf Feature = 1 << iota
	FeatureServerStreaming
	FeatureCallOptions
)

type FeedbackConfig

type FeedbackConfig struct {
	MaxAge      time.Duration
	MaxMethods  int
	ObserveOnly bool
}

type FeedbackMethod

type FeedbackMethod struct {
	Method              string
	Active, Recommended int
	Sequence            uint64
	Fresh               bool
}

type FeedbackStats

type FeedbackStats struct {
	Enabled                    bool
	Accepted, Ignored, Limited uint64
	Methods                    []FeedbackMethod
}

type GovernanceConfig

type GovernanceConfig struct {
	MaxExecuting, QueueCapacity, SampleWindow int
	QueueTimeout, FeedbackTTL                 time.Duration
	QueuePolicy                               QueuePolicy
	Adaptive, Feedback                        bool
	Methods                                   []MethodPolicy
}

type GovernanceSnapshot

type GovernanceSnapshot struct {
	Enabled, Adaptive bool
	Epoch             string
	Executing, Queued int
	Methods           []MethodState
	Decisions         []ControlDecision
	DroppedDecisions  uint64
}

type HealthStatus

type HealthStatus struct {
	Serving bool   `json:"serving"`
	State   string `json:"state"`
}

type IOConfig

type IOConfig struct {
	// MaxFrameBytes bounds an entire payload, including Open metadata.
	MaxFrameBytes uint32
	WriteTimeout  time.Duration
	// ReadTimeout bounds the time to read one complete record, including idle.
	ReadTimeout time.Duration
}

type Identity

type Identity struct {
	Subject string
	Claims  map[string]string
}

func AuthenticatedIdentity

func AuthenticatedIdentity(ctx context.Context) (Identity, bool)

type Interceptor

type Interceptor func(context.Context, CallInfo) (context.Context, func(CallResult), error)

Interceptor enters once, in registration order. Finish runs once in reverse order, with no framework mutex held. Server finishes measure handler lifecycle; client stream finishes observe protocol completion, not user consumption. Hooks are cooperative user code and must return; panics become Internal.

func Credentials

func Credentials(provider func(context.Context) (Metadata, error)) Interceptor

Credentials supplies outgoing call metadata before serialization. Providers must honor ctx, and bearer credentials should use authenticated TLS/QUIC.

func LoggingInterceptor

func LoggingInterceptor(logger *slog.Logger) Interceptor

type MemoryAccount

type MemoryAccount struct {
	// contains filtered or unexported fields
}

func (*MemoryAccount) ID

func (a *MemoryAccount) ID() uint64

func (*MemoryAccount) Release

func (a *MemoryAccount) Release() error

Release removes a quiescent account. Closing a socket alone cannot forgive leases held by a user codec or an unread stream. Retire never frees bytes.

func (*MemoryAccount) Retire

func (a *MemoryAccount) Retire()

func (*MemoryAccount) Snapshot

func (a *MemoryAccount) Snapshot() MemoryAccountStats

type MemoryAccountStats

type MemoryAccountStats struct {
	ID                                    uint64
	Retired, Bound, OwnerClosed, Released bool
	Memory                                MemoryStats
	DataBytes, TotalBytes                 int64
	Leases, EncodingWaiters               int
	Unread                                BufferStats
}

type MemoryConfig

type MemoryConfig struct{ ReceiveBytes, SendBytes, ControlBytes, EncodingBytes int64 }

MemoryConfig bounds retained framework record buffers, not arbitrary application allocations, decoded response objects, QUIC internals or RSS.

type MemoryGroupStats

type MemoryGroupStats struct {
	Accounts, Leases, EncodingWaiters int
	Bytes                             MemoryUsage
	DataBytes                         int64
	Unread                            BufferUsage // Current group occupancy; peaks are reported at pool/account level.
}

type MemoryPool

type MemoryPool struct {
	// contains filtered or unexported fields
}

MemoryPool owns only accounting, never sockets, request tables or user buffers. All attached local and aggregate budgets use this single mutex. No pool method calls into a connection or routing, which keeps the lock order one-way.

func NewMemoryPool

func NewMemoryPool(cfg MemoryPoolConfig, maxAccounts int) (*MemoryPool, error)

func (*MemoryPool) Accounts

func (p *MemoryPool) Accounts() []MemoryAccountStats

func (*MemoryPool) CheckClient

func (p *MemoryPool) CheckClient(cfg ClientConfig) error

CheckClient validates capacity for a maximum prepared OPEN plus its send lease. It does not reserve an account or bind it to a client.

func (*MemoryPool) NewAccount

func (p *MemoryPool) NewAccount() (*MemoryAccount, error)

func (*MemoryPool) Seal

func (p *MemoryPool) Seal()

func (*MemoryPool) Stats

func (p *MemoryPool) Stats() MemoryPoolStats

type MemoryPoolConfig

type MemoryPoolConfig struct {
	Memory    MemoryConfig
	DataBytes int64
}

MemoryPoolConfig limits aggregate framework buffers. DataBytes covers encoding, receive and send together. Control receive/send each retain a separate bound. Zero values use 32 MiB data, 16 MiB per data class and 64 KiB per control class.

type MemoryPoolStats

type MemoryPoolStats struct {
	Memory                        MemoryStats
	Data, Total                   ByteStats
	Active, Retired               MemoryGroupStats
	Unread                        BufferStats
	Accounts, PeakAccounts, Limit int
	Created, Released             uint64
	Sealed                        bool
}

type MemoryStats

type MemoryStats struct{ Receive, Send, ControlReceive, ControlSend, Encoding ByteStats }

type MemoryUsage

type MemoryUsage struct{ Receive, Send, ControlReceive, ControlSend, Encoding int64 }

type Metadata

type Metadata map[string]string

Metadata is UTF-8 call metadata. Keys are lowercase ASCII; credentials are untrusted until Authenticate validates them. Values are never logged by core.

func IncomingMetadata

func IncomingMetadata(ctx context.Context) Metadata

func OutgoingMetadata

func OutgoingMetadata(ctx context.Context) Metadata

type MetadataCapture

type MetadataCapture struct {
	// contains filtered or unexported fields
}

MetadataCapture reads response trailers safely, including while a call runs. Trailers become available with END; they are not initial response headers.

func (*MetadataCapture) Snapshot

func (c *MetadataCapture) Snapshot() Metadata

type MethodInfo

type MethodInfo struct {
	Path      string `json:"path"`
	Streaming bool   `json:"streaming"`
	Codec     string `json:"codec"`
}

type MethodPolicy

type MethodPolicy struct {
	Method                    string
	Weight, Min, Initial, Max int
	Target                    time.Duration
	// FallbackLimit=0 disables the guard. Otherwise sustained successful
	// windows above Target at Min latch this operator-chosen fixed limit.
	FallbackLimit, FallbackWindows int
}

type MethodState

type MethodState struct {
	Method                         string
	Limit, Running, Queued, Weight int
	Samples                        uint64
	P90                            time.Duration
	Mode                           ControlMode
	UnmetWindows                   int
	Generation, Fallbacks, Resets  uint64
}

type Metrics

type Metrics struct {
	// contains filtered or unexported fields
}

Metrics exports bounded Prometheus exposition. Auth/body/identity values are never labels. Server hooks measure worker time; core admission/fault gauges are exported independently so refusals remain visible.

func NewMetrics

func NewMetrics(maxSeries int) *Metrics

func (*Metrics) AttachServer

func (m *Metrics) AttachServer(s *Server)

func (*Metrics) Interceptor

func (m *Metrics) Interceptor() Interceptor

func (*Metrics) ServeHTTP

func (m *Metrics) ServeHTTP(w http.ResponseWriter, r *http.Request)

type Peer

type Peer struct {
	Address   string
	Transport Transport
	TLS       *tls.ConnectionState
}

func PeerFromContext

func PeerFromContext(ctx context.Context) (Peer, bool)

PeerFromContext exposes transport-authenticated connection information; token identities are separately available through AuthenticatedIdentity.

type PipelineConfig

type PipelineConfig struct {
	Timeout      time.Duration
	MaxInFlight  int
	RateLimiter  *RateLimiter
	Interceptors []Interceptor
	Retry        RetryPolicy
}

type Pressure

type Pressure struct {
	Version                                          int    `json:"v"`
	Epoch                                            string `json:"epoch"`
	Sequence                                         uint64 `json:"seq"`
	TTLMillis                                        int64  `json:"ttl_ms"`
	Method                                           string `json:"method"`
	Limit, Running, Queued, PeersDemand, Recommended int
	ReceiveUsed, ReceiveLimit                        int64
}

Pressure is advisory metadata from an authenticated/configured peer, not a distributed lease, reservation, tenant identity or authorization decision.

type ProtobufMethod

type ProtobufMethod struct {
	Path       string
	NewRequest func() proto.Message
	Unary      func(context.Context, proto.Message) (proto.Message, error)
	Stream     func(context.Context, proto.Message, func(proto.Message) error) error
}

ProtobufMethod binds one method to fresh request messages. Exactly one of Unary or Stream must be set. Generated registration supplies typed adapters.

type ProtobufRequest

type ProtobufRequest struct {
	// contains filtered or unexported fields
}

ProtobufRequest selects binary Protobuf for one call, including its responses. Construct it with Protobuf. JSON remains the default for unwrapped requests.

func Protobuf

func Protobuf(message proto.Message) ProtobufRequest

Protobuf wraps a message without encoding it. Admission and byte reservation still happen before user message code runs. Do not mutate a message during Call or Stream creation; the Protobuf runtime does not support concurrent mutation.

type QUICClient

type QUICClient struct {
	// contains filtered or unexported fields
}

QUICClient owns one authenticated physical session. Each Call/Stream opens an independent native exchange, with no retries or hidden TCP downgrade.

func DialQUIC

func DialQUIC(ctx context.Context, address string, security TLSOptions, options QUICConfig, cfg ClientConfig) (*QUICClient, error)

func (*QUICClient) AdmissionStats

func (c *QUICClient) AdmissionStats() AdmissionStats

func (*QUICClient) BufferStats

func (c *QUICClient) BufferStats() BufferStats

func (*QUICClient) Call

func (c *QUICClient) Call(ctx context.Context, method string, request, response any) error

func (*QUICClient) Capabilities

func (c *QUICClient) Capabilities() Capabilities

func (*QUICClient) Close

func (c *QUICClient) Close()

func (*QUICClient) CompressionStats

func (c *QUICClient) CompressionStats() CompressionStats

func (*QUICClient) FeedbackStats

func (c *QUICClient) FeedbackStats() FeedbackStats

func (*QUICClient) MemoryStats

func (c *QUICClient) MemoryStats() MemoryStats

func (*QUICClient) OpenStream

func (c *QUICClient) OpenStream(ctx context.Context, method string, request any) (Receiver, error)

func (*QUICClient) Stats

func (c *QUICClient) Stats() QUICStats

func (*QUICClient) Stream

func (c *QUICClient) Stream(ctx context.Context, method string, request any) (*Stream, error)

func (*QUICClient) WaitIdle

func (c *QUICClient) WaitIdle(ctx context.Context) error

type QUICConfig

type QUICConfig struct {
	KeepAlivePeriod    time.Duration
	MaxStreams         int
	IdleTimeout        time.Duration
	FirstRecordTimeout time.Duration
}

type QUICListener

type QUICListener struct {
	// contains filtered or unexported fields
}

QUICListener explicitly owns a packet socket and transport. Stopping new handshakes is separate from closing accepted sessions and the UDP socket.

func ListenQUIC

func ListenQUIC(address string, security TLSOptions, options QUICConfig) (*QUICListener, error)

func (*QUICListener) Addr

func (l *QUICListener) Addr() net.Addr

func (*QUICListener) Close

func (l *QUICListener) Close() error

type QUICStats

type QUICStats struct {
	CloseConfirmed                        bool
	Active                                int
	Opened, Retired                       uint64
	RTT                                   time.Duration
	BytesSent, BytesReceived, PacketsLost uint64
}

type QueuePolicy

type QueuePolicy string
const (
	FIFO       QueuePolicy = "fifo"
	MethodFair QueuePolicy = "method_fair"
)

type RateLimitError

type RateLimitError struct{ Method string }

func (*RateLimitError) Error

func (e *RateLimitError) Error() string

func (*RateLimitError) Unwrap

func (e *RateLimitError) Unwrap() error

type RateLimiter

type RateLimiter struct {
	// contains filtered or unexported fields
}

func NewRateLimiter

func NewRateLimiter(policies map[string]RateSpec) (*RateLimiter, error)

NewRateLimiter compiles a bounded static policy table. "*" is a shared total bucket, not a dynamically growing per-method or per-tenant cache.

func (*RateLimiter) Allow

func (r *RateLimiter) Allow(method string) error

func (*RateLimiter) Stats

func (r *RateLimiter) Stats() RateStats

type RateSpec

type RateSpec struct {
	PerSecond float64
	Burst     int
}

type RateStats

type RateStats struct {
	Rejected uint64
	Policies int
}

type Receiver

type Receiver interface {
	Recv(any) error
	Close() error
}

Receiver is shared by direct and routing-managed streams. Close releases a stream early; EOF and errors also let a routing stream release its references.

type RetryPolicy

type RetryPolicy struct {
	MaxAttempts       int
	Backoff           time.Duration
	IdempotentMethods []string
}

type Sender

type Sender struct {
	// contains filtered or unexported fields
}

Sender is valid only during its handler invocation. Send is serialized and waits for receiver credits without blocking the connection's control reader. Body is preencoded using the registered method's codec. Protobuf handlers normally use the typed send callback instead of calling Sender directly.

func (*Sender) Send

func (out *Sender) Send(body json.RawMessage) error

type Server

type Server struct {
	// contains filtered or unexported fields
}

Server owns a listener after Serve succeeds, every accepted connection, and every admitted handler. Handler registration freezes at Serve.

func NewServer

func NewServer(cfg ServerConfig) (*Server, error)

func (*Server) Close

func (s *Server) Close()

func (*Server) CompressionStats

func (s *Server) CompressionStats() CompressionStats

func (*Server) Drain

func (s *Server) Drain(ctx context.Context) error

Drain seals admission under the same lock used by admit. Successful normal results are kept alive through receipt ACK; the caller deadline bounds drain.

func (*Server) DrainWithReport

func (s *Server) DrainWithReport(ctx context.Context) (report DrainReport, err error)

DrainWithReport retains both a context failure and ErrDelivery when present. With only cumulative delivery faults it returns ErrDelivery, as Drain does.

Example
package main

import (
	"context"
	"fmt"
	"net"
	"time"

	rpc "github.com/KanaDoodle/KanaRPC"
)

func main() {
	ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
	defer cancel()
	s, err := rpc.NewServer(rpc.ServerConfig{})
	if err != nil {
		panic(err)
	}
	if err := rpc.RegisterUnary(s, "/example/echo", func(_ context.Context, n int) (int, error) { return n, nil }); err != nil {
		panic(err)
	}
	l, err := net.Listen("tcp", "127.0.0.1:0")
	if err != nil {
		panic(err)
	}
	done := make(chan error, 1)
	go func() { done <- s.Serve(l) }()
	defer s.Close()
	c, err := rpc.Dial(ctx, l.Addr().String(), rpc.ClientConfig{})
	if err != nil {
		panic(err)
	}
	defer c.Close()
	var out int
	if err := c.Call(ctx, "/example/echo", 42, &out); err != nil {
		panic(err)
	}
	// Use a fresh shutdown context, not a canceled request context.
	shutdown, stop := context.WithTimeout(context.Background(), time.Second)
	defer stop()
	report, err := s.DrainWithReport(shutdown)
	if err != nil {
		panic(err)
	} // Inspect errors.Is(err, rpc.ErrDelivery) and ctx errors separately.
	if err := <-done; err != nil {
		panic(err)
	}
	fmt.Println(out, report.Quiescent, report.TotalFaults.LostTerminals)
}
Output:
42 true 0

func (*Server) Governance

func (s *Server) Governance() GovernanceSnapshot

func (*Server) HandleStream

func (s *Server) HandleStream(path string, h StreamHandler) error

func (*Server) HandleUnary

func (s *Server) HandleUnary(path string, h UnaryHandler) error

func (*Server) Health

func (s *Server) Health() HealthStatus

func (*Server) HealthHandler

func (s *Server) HealthHandler() http.Handler

HealthHandler is for an explicitly bound administrative listener.

func (*Server) MemoryStats

func (s *Server) MemoryStats() MemoryStats

func (*Server) Methods

func (s *Server) Methods() []MethodInfo

func (*Server) Ready

func (s *Server) Ready() bool

func (*Server) ResetAdaptive

func (s *Server) ResetAdaptive(path string) error

ResetAdaptive is a local operator action, never an automatic business retry. Existing handlers keep their slots but cannot sample into the new generation.

func (*Server) Serve

func (s *Server) Serve(listener net.Listener) error

Serve transfers listener ownership only if the server has not started or closed. It returns when acceptance stops; Drain/Wait cover admitted work.

func (*Server) ServeQUIC

func (s *Server) ServeQUIC(listener *QUICListener) error

func (*Server) ServeTLS

func (s *Server) ServeTLS(listener net.Listener, options TLSOptions) error

ServeTLS counts accepted sockets, including pending bounded handshakes, against MaxConnections. A stalled handshake does not block other accepts.

func (*Server) SetServing

func (s *Server) SetServing(serving bool)

func (*Server) Stats

func (s *Server) Stats() ServerStats

func (*Server) Wait

func (s *Server) Wait(ctx context.Context) error

Wait joins owned connection readers and handlers, including handlers that ignore cancellation. It never claims to forcibly terminate Go functions.

type ServerConfig

type ServerConfig struct {
	Compression    *CompressionConfig
	TCPKeepAlive   *TCPKeepAliveConfig
	Interceptors   []Interceptor
	Authenticate   Authenticator
	RateLimiter    *RateLimiter
	Trace          *TraceRecorder // nil disables the bounded local decision journal
	Governance     *GovernanceConfig
	Memory         MemoryConfig
	IO             IOConfig
	MaxConnections int
	// MaxInFlight includes queued work, handlers and terminal-ACK/FIN waiters.
	MaxInFlight        int
	MaxPerConnection   int
	MaxRequestDuration time.Duration
	AckTimeout         time.Duration
}

type ServerOutcomes

type ServerOutcomes struct {
	CapacityRejected, PolicyRejected, DrainingRejected, InvalidRejected, NotFoundRejected uint64
	CancelRequests, RequestDeadlines, TransportAborts, ShutdownAborts, BudgetAborts       uint64
	// ReceiptsResolved equals Delivered + LostTerminals + the two outcomes below.
	// An active receipt wait is not included until it is settled.
	ReceiptsResolved, ReceiptsCanceled, ReceiptsDeadlineExceeded uint64
}

ServerOutcomes contains cumulative observations, not disjoint RPC totals. CancelRequests counts the first CANCEL observed for an active execution, even after END; it does not assert cancellation won. Business status codes do not increment these counters. Byte refusals live in MemoryStats.Rejected.

type ServerStats

type ServerStats struct {
	// Canceled is the legacy handler-status count, including deadline statuses.
	// Outcomes records protocol observations separately from application codes.
	Outcomes                                                          ServerOutcomes
	Queued                                                            int
	IncompleteExchanges                                               uint64
	NativeStreams                                                     int
	Connections, InFlight, Executing                                  int
	Admitted, Completed, Rejected, Canceled, Delivered, LostTerminals uint64
}

type ServiceCaller

type ServiceCaller interface {
	Call(context.Context, string, any, any) error
	OpenStream(context.Context, string, any) (Receiver, error)
}

ServiceCaller is the transport-independent interface used by generated SDKs. Implementations honor Protobuf(request) and preserve stream ownership.

func AsServiceCaller

func AsServiceCaller(c Caller) ServiceCaller

AsServiceCaller bridges the older concrete-Stream Caller contract without changing implementations or introducing a second call lifecycle.

type Status

type Status struct {
	Code    Code   `json:"code"`
	Message string `json:"message,omitempty"`
}

func (*Status) Error

func (s *Status) Error() string

func (*Status) Is

func (s *Status) Is(target error) bool

type Stream

type Stream struct {
	// contains filtered or unexported fields
}

func (*Stream) Close

func (s *Stream) Close() error

func (*Stream) Done

func (s *Stream) Done() <-chan struct{}

func (*Stream) Outcome

func (s *Stream) Outcome() error

func (*Stream) Recv

func (s *Stream) Recv(response any) error

Recv drains ordered chunks before a remote terminal error/EOF. Local cancellation discards buffered chunks. Concurrent Recv calls are serialized.

type StreamHandler

type StreamHandler func(context.Context, json.RawMessage, *Sender) error

type TCPKeepAliveConfig

type TCPKeepAliveConfig struct {
	Idle, Interval time.Duration
	Count          int
}

type TLSOptions

type TLSOptions struct {
	Config           *tls.Config
	HandshakeTimeout time.Duration
}

type TraceConfig

type TraceConfig struct {
	Capacity    int
	SampleEvery uint64 // deterministic sampling by local channel/request pair
}

TraceRecorder is an opt-in, bounded local decision journal, not a distributed trace or delivery ledger. Writers never wait for the reader or call user code. Dropped/overwritten events make incomplete timelines explicit.

type TraceEvent

type TraceEvent struct {
	TraceRef
	Sequence uint64    `json:"sequence"`
	At       time.Time `json:"at"`
	Kind     string    `json:"kind"`
	Reason   string    `json:"reason,omitempty"`
	Code     Code      `json:"code,omitempty"`
	Value    int64     `json:"value,omitempty"`
	Next     int64     `json:"next,omitempty"`
}

type TraceRecorder

type TraceRecorder struct {
	// contains filtered or unexported fields
}

func NewTraceRecorder

func NewTraceRecorder(c TraceConfig) (*TraceRecorder, error)

func (*TraceRecorder) Snapshot

func (r *TraceRecorder) Snapshot(after uint64, limit int) TraceSnapshot

Snapshot copies at most 1024 events. RPC writers skip a busy journal instead of waiting behind this copy. Memory is fixed at construction; no body is kept.

type TraceRef

type TraceRef struct {
	Channel uint64 `json:"channel"`
	Request uint64 `json:"request"`
	Method  string `json:"method"`
}

func RequestTrace

func RequestTrace(ctx context.Context) (TraceRef, bool)

RequestTrace returns local identity only when the server journal is enabled. It contains no propagated user identity and grants no permissions.

type TraceSnapshot

type TraceSnapshot struct {
	Events      []TraceEvent `json:"events"`
	Capacity    int          `json:"capacity"`
	SampleEvery uint64       `json:"sample_every"`
	Last        uint64       `json:"last"`
	Oldest      uint64       `json:"oldest"`
	Dropped     uint64       `json:"dropped"`
	Overwritten uint64       `json:"overwritten"`
	SampledOut  uint64       `json:"sampled_out"`
	Gap         bool         `json:"gap"`
}

type Transport

type Transport string
const (
	TCP  Transport = "tcp"
	TLS  Transport = "tls"
	QUIC Transport = "quic"
)

type UnaryHandler

type UnaryHandler func(context.Context, json.RawMessage) (json.RawMessage, error)

Directories

Path Synopsis
cmd
governance-lab command
governance-lab measures real loopback RPC around a bounded timer/slot fixture.
governance-lab measures real loopback RPC around a bounded timer/slot fixture.
kanarpc command
kanarpc is a JSON call/stream/health/method-list CLI for KNR2 endpoints.
kanarpc is a JSON call/stream/health/method-list CLI for KNR2 endpoints.
lifecycle-demo command
lifecycle-demo exercises the v2 transport with two owned loopback processes.
lifecycle-demo exercises the v2 transport with two owned loopback processes.
pool-lab command
pool-lab uses resource-lab's real workers and a local snapshot fixture.
pool-lab uses resource-lab's real workers and a local snapshot fixture.
production-demo command
production-demo executes the complete local integration chain.
production-demo executes the complete local integration chain.
protobuf-demo command
protobuf-demo runs a generated SDK against a real loopback TCP server.
protobuf-demo runs a generated SDK against a real loopback TCP server.
protoc-gen-kanarpc command
protoc-gen-kanarpc generates typed KanaRPC clients and service registration.
protoc-gen-kanarpc generates typed KanaRPC clients and service registration.
resource-lab command
resource-lab is an owned loopback resource experiment, not model inference.
resource-lab is an owned loopback resource experiment, not model inference.
routing-lab command
routing-lab is an independent client for transport-lab workers.
routing-lab is an independent client for transport-lab workers.
showcase command
showcase runs a local RPC governance console with embedded web assets.
showcase runs a local RPC governance console with embedded web assets.
transport-lab command
transport-lab uses integer IDs and fixed JSON chunks, never a model backend.
transport-lab uses integer IDs and fixed JSON chunks, never a model backend.
Package discovery owns explicit etcd registrations and fresh resolver snapshots.
Package discovery owns explicit etcd registrations and fresh resolver snapshots.
examples
internal
netfault
Package netfault is an owned single-client UDP test relay.
Package netfault is an owned single-client UDP test relay.
protogen
Package protogen emits Go bindings for KanaRPC unary and server-streaming RPCs.
Package protogen emits Go bindings for KanaRPC unary and server-streaming RPCs.
testcert
Package testcert creates ephemeral localhost credentials for tests and labs.
Package testcert creates ephemeral localhost credentials for tests and labs.
wire
Package wire implements the experimental KanaRPC v2 record format.
Package wire implements the experimental KanaRPC v2 record format.
Package observability adapts the common KanaRPC lifecycle hook to OTel.
Package observability adapts the common KanaRPC lifecycle hook to OTel.
Package routing owns discovery-driven connection lifetimes.
Package routing owns discovery-driven connection lifetimes.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL