service

Documentation

Index

• func AddTransportOnContext(ctx context.Context) context.Context
• type Manager
  • func NewManager(configs map[string]*runtimecfg.ServiceInfo, routinePool *safe.Pool, ...) *Manager
  • func (m *Manager) BuildHTTP(rootCtx context.Context, serviceName string) (http.Handler, error)
  • func (m *Manager) SetMiddlewareChainBuilder(middlewareChainBuilder middlewareChainBuilder)
• type ManagerFactory
• type ProxyBuilder
• type ServiceBuilder
• type SpiffeX509Source
• type TransportManager
  • func NewTransportManger(log *zap.Logger, spiffeXSource SpiffeX509Source) *TransportManager
  • func (t *TransportManager) Get(name string) (*dynamic.ServersTransport, error)
  • func (t *TransportManager) GetRoundTripper(name string) (http.RoundTripper, error)
  • func (t *TransportManager) GetTLSConfig(name string) (*tls.Config, error)
  • func (t *TransportManager) Update(newConfigs map[string]*dynamic.ServersTransport)

Functions

func AddTransportOnContext

func AddTransportOnContext(ctx context.Context) context.Context

AddTransportOnContext 在 context 中注入 stickyRoundTripper 标记。

使用示例：

// 在中间件或路由层标记该请求可能需要连接黏滞
ctx = AddTransportOnContext(ctx)
req = req.WithContext(ctx)
// 后续 kerberosRoundTripper.RoundTrip 会检查该标记

Types

type Manager

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

func NewManager

func NewManager(configs map[string]*runtimecfg.ServiceInfo,
	routinePool *safe.Pool,
	transportManager httputil.TransportManager,
	proxyBuilder ProxyBuilder,
	serviceBuilders ...ServiceBuilder,
) *Manager

func (*Manager) BuildHTTP

func (m *Manager) BuildHTTP(rootCtx context.Context, serviceName string) (http.Handler, error)

func (*Manager) SetMiddlewareChainBuilder

func (m *Manager) SetMiddlewareChainBuilder(middlewareChainBuilder middlewareChainBuilder)

type ManagerFactory

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

ManagerFactory a factory of service manager

type ProxyBuilder

type ProxyBuilder interface {
	Build(cfgName string, targetURL *url.URL, passHostHeader, preservePath bool, flushInterval time.Duration) (http.Handler, error)
	Update(configs map[string]*dynamic.ServersTransport)
}

type ServiceBuilder

type ServiceBuilder interface {
	BuildHTTP(rootCtx context.Context, serviceName string) (http.Handler, error)
}

type SpiffeX509Source

type SpiffeX509Source interface {
	x509svid.Source
	x509bundle.Source
}

SpiffeX509Source 是 SPIFFE X.509 SVID 源接口。 它组合了两个能力：

• x509svid.Source：提供自身 SVID（GetX509SVID），用于 mTLS 客户端证书
• x509bundle.Source：提供信任域 Bundle（GetX509BundleForTrustDomain），用于验证对端证书

使用示例：

source, _ := workloadapi.NewX509Source(ctx,
    workloadapi.WithClientOptions(workloadapi.WithAddr("unix:///run/spire/sockets/agent.sock")),
)
tm := NewTransportManger(source) // source 同时满足两个 Source 接口

type TransportManager

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

TransportManager HTTP 传输层管理器。

负责管理 HTTP 反向代理到后端服务时使用的 http.RoundTripper 和 tls.Config。 当动态配置更新时，按照最小变更原则增量更新：

• 旧配置中仍存在的项 → 对比差异，有变化才重建
• 旧配置中被删除的项 → 清理
• 新配置中新增的项 → 创建

每个 RoundTripper 关联一个 TLS 配置，支持三种 TLS 模式：

1. SPIFFE mTLS：通过 Workload API 获取身份证书
2. 传统 TLS/mTLS：自定义 CA、客户端证书、cipher suite 等
3. 无 TLS：纯 HTTP 直连

使用示例：

cfg := map[string]*dynamic.ServersTransport{
    "my-api@internal": {
        ServerName: "api.example.com",
        RootCAs:    []types.FileOrContent{"ca-cert.pem"},
    },
}
tm.Update(cfg)                                    // 更新配置
rt, err := tm.GetRoundTripper("my-api@internal")  // 获取对应的 RoundTripper
resp, _ := rt.RoundTrip(req)

func NewTransportManger

func NewTransportManger(log *zap.Logger, spiffeXSource SpiffeX509Source) *TransportManager

NewTransportManger 创建传输管理器实例。 spiffeXSource 可以为 nil（不使用 SPIFFE 的场景）。

func (*TransportManager) Get

func (t *TransportManager) Get(name string) (*dynamic.ServersTransport, error)

Get 根据 transport 名称获取原始 ServersTransport 配置。

使用示例：

cfg, _ := tm.Get("my-api@file")
fmt.Printf("ServerName: %s\n", cfg.ServerName)

func (*TransportManager) GetRoundTripper

func (t *TransportManager) GetRoundTripper(name string) (http.RoundTripper, error)

GetRoundTripper 根据 transport 名称获取对应的 RoundTripper。

名称规则：

• 空字符串 → 自动替换为 "default@internal"（内置默认 transport）
• "name@provider" → 精确匹配（来自动态配置中的 serversTransports 定义）

使用示例：

// 获取默认 transport
rt, _ := tm.GetRoundTripper("")

// 获取特定 transport
rt, _ := tm.GetRoundTripper("my-api@file")
resp, _ := rt.RoundTrip(req)

func (*TransportManager) GetTLSConfig

func (t *TransportManager) GetTLSConfig(name string) (*tls.Config, error)

GetTLSConfig 根据 transport 名称获取对应的 tls.Config。

使用示例：

tlsCfg, _ := tm.GetTLSConfig("my-api@file")

func (*TransportManager) Update

func (t *TransportManager) Update(newConfigs map[string]*dynamic.ServersTransport)

Update 增量更新所有 ServersTransport 配置。

两阶段 diff 算法：

阶段一：遍历旧配置 → 删除不存在的项，更新有变化的项
阶段二：遍历新配置 → 创建新增的项

使用示例：

// 首次更新：创建两个 transport
tm.Update(map[string]*dynamic.ServersTransport{
    "api@internal": {ServerName: "api.example.com"},
    "db@internal":  {InsecureSkipVerify: true},
})

// 二次更新："api@internal" 配置不变→跳过重建；删除 "db@internal"；新增 "cache@internal"
tm.Update(map[string]*dynamic.ServersTransport{
    "api@internal":   {ServerName: "api.example.com"},    // 不变，跳过
    "cache@internal": {ServerName: "cache.example.com"},   // 新增
})