wangjia
6ec7cd8146
合并 proto 契约 + buf 工具链任务到 main（已含 apierr + idgen + CONVENTIONS.md）： - server/proto/pangolin/agent/v1/agent.proto: AgentService 6 个 RPC（Enroll/Register/ Heartbeat/Subscribe/Ack/ReportUsage）及全量消息类型，隐私红线注释保留 - server/buf.yaml: v2 格式，STANDARD lint + FILE breaking 规则 - server/buf.gen.yaml: remote protoc-gen-go v1.36.4 + protoc-gen-go-grpc v1.5.1 插件 - server/internal/pb/: 生成的 agent.pb.go + agent_grpc.pb.go 提交入库 - server/Makefile: 新增 proto / proto-lint / proto-breaking 目标 - server/tools.go: 新增 buf v1.70.0、protoc-gen-go、protoc-gen-go-grpc 工具依赖 - server/go.mod / go.sum: 合并 buf 工具链依赖；github.com/google/uuid 保留为 direct 依赖（idgen 直接 import）；go 版本升至 1.25.10 冲突解决：两侧均修改 go.mod，以 proto 分支（超集）为基础，将 google/uuid 移至 直接依赖 require 块，保留 apierr/idgen 的已有文件不变。 go build ./... ✓ | go test ./internal/apierr/... ./internal/idgen/... ✓ Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
361 lines
16 KiB
Go
361 lines
16 KiB
Go
// agent.proto — Control-plane ↔ Agent 通信契约
|
||
//
|
||
// 安全红线（禁止违反）：
|
||
// 1. 所有消息中只使用 dp_uuid 标识数据通道，严禁出现 user_id / email 等用户身份字段。
|
||
// 2. ReportUsage 不含目的地址、DNS 查询等任何可还原用户行为的字段（无日志口径）。
|
||
// 3. 本文件冻结后，任何 breaking change 须先通过 buf breaking 审查。
|
||
|
||
// Code generated by protoc-gen-go-grpc. DO NOT EDIT.
|
||
// versions:
|
||
// - protoc-gen-go-grpc v1.5.1
|
||
// - protoc (unknown)
|
||
// source: pangolin/agent/v1/agent.proto
|
||
|
||
package agentv1
|
||
|
||
import (
|
||
context "context"
|
||
grpc "google.golang.org/grpc"
|
||
codes "google.golang.org/grpc/codes"
|
||
status "google.golang.org/grpc/status"
|
||
)
|
||
|
||
// This is a compile-time assertion to ensure that this generated file
|
||
// is compatible with the grpc package it is being compiled against.
|
||
// Requires gRPC-Go v1.64.0 or later.
|
||
const _ = grpc.SupportPackageIsVersion9
|
||
|
||
const (
|
||
AgentService_Enroll_FullMethodName = "/pangolin.agent.v1.AgentService/Enroll"
|
||
AgentService_Register_FullMethodName = "/pangolin.agent.v1.AgentService/Register"
|
||
AgentService_Heartbeat_FullMethodName = "/pangolin.agent.v1.AgentService/Heartbeat"
|
||
AgentService_Subscribe_FullMethodName = "/pangolin.agent.v1.AgentService/Subscribe"
|
||
AgentService_Ack_FullMethodName = "/pangolin.agent.v1.AgentService/Ack"
|
||
AgentService_ReportUsage_FullMethodName = "/pangolin.agent.v1.AgentService/ReportUsage"
|
||
)
|
||
|
||
// AgentServiceClient is the client API for AgentService service.
|
||
//
|
||
// For semantics around ctx use and closing/ending streaming RPCs, please refer to https://pkg.go.dev/google.golang.org/grpc/?tab=doc#ClientConn.NewStream.
|
||
//
|
||
// AgentService 是控制面暴露给 Agent 的唯一 gRPC 接口。
|
||
// 连接方向：Agent 主动拨号控制面。
|
||
// 除 Enroll 外，所有 RPC 均需通过 mTLS 客户端证书鉴权。
|
||
type AgentServiceClient interface {
|
||
// Enroll 供新节点申请证书。唯一不要求 mTLS 客户端证书的入口。
|
||
// Agent 提交 bootstrap_token（云初始化注入）与 CSR，控制面签发短期证书。
|
||
Enroll(ctx context.Context, in *EnrollRequest, opts ...grpc.CallOption) (*EnrollResponse, error)
|
||
// Register 是 mTLS 建立后的首次调用，返回该节点的全量配置快照。
|
||
// ConfigSnapshot 直接作为响应类型（非 RegisterResponse），是有意设计——快照兼用于
|
||
// ApplyConfig 下发，避免重复定义。buf:lint:ignore 声明如下。
|
||
// buf:lint:ignore RPC_RESPONSE_STANDARD_NAME
|
||
Register(ctx context.Context, in *RegisterRequest, opts ...grpc.CallOption) (*ConfigSnapshot, error)
|
||
// Heartbeat 由 Agent 每 30 秒发送一次，上报实时负载并与控制面对账配置版本。
|
||
// 若 need_full_resync == true，Agent 应主动重新调用 Register。
|
||
Heartbeat(ctx context.Context, in *HeartbeatRequest, opts ...grpc.CallOption) (*HeartbeatResponse, error)
|
||
// Subscribe 建立控制面 → Agent 的服务端流，用于下发 Command。
|
||
// Agent 重连时携带 last_command_id，控制面补发缺失命令（at-least-once 语义）。
|
||
// Command 直接作为流元素类型（非 SubscribeResponse），是有意设计——下游消费者
|
||
// 直接操作 Command，无需额外包装。buf:lint:ignore 声明如下。
|
||
// buf:lint:ignore RPC_RESPONSE_STANDARD_NAME
|
||
Subscribe(ctx context.Context, in *SubscribeRequest, opts ...grpc.CallOption) (grpc.ServerStreamingClient[Command], error)
|
||
// Ack 用于 Agent 向控制面回执命令的执行结果。
|
||
Ack(ctx context.Context, in *AckRequest, opts ...grpc.CallOption) (*AckResponse, error)
|
||
// ReportUsage 上报各数据通道的流量用量，供计费/限速使用。
|
||
// 红线：items 中只含 dp_uuid 与字节/分钟计数，不含目的地址或 DNS 字段。
|
||
ReportUsage(ctx context.Context, in *ReportUsageRequest, opts ...grpc.CallOption) (*ReportUsageResponse, error)
|
||
}
|
||
|
||
type agentServiceClient struct {
|
||
cc grpc.ClientConnInterface
|
||
}
|
||
|
||
func NewAgentServiceClient(cc grpc.ClientConnInterface) AgentServiceClient {
|
||
return &agentServiceClient{cc}
|
||
}
|
||
|
||
func (c *agentServiceClient) Enroll(ctx context.Context, in *EnrollRequest, opts ...grpc.CallOption) (*EnrollResponse, error) {
|
||
cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
|
||
out := new(EnrollResponse)
|
||
err := c.cc.Invoke(ctx, AgentService_Enroll_FullMethodName, in, out, cOpts...)
|
||
if err != nil {
|
||
return nil, err
|
||
}
|
||
return out, nil
|
||
}
|
||
|
||
func (c *agentServiceClient) Register(ctx context.Context, in *RegisterRequest, opts ...grpc.CallOption) (*ConfigSnapshot, error) {
|
||
cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
|
||
out := new(ConfigSnapshot)
|
||
err := c.cc.Invoke(ctx, AgentService_Register_FullMethodName, in, out, cOpts...)
|
||
if err != nil {
|
||
return nil, err
|
||
}
|
||
return out, nil
|
||
}
|
||
|
||
func (c *agentServiceClient) Heartbeat(ctx context.Context, in *HeartbeatRequest, opts ...grpc.CallOption) (*HeartbeatResponse, error) {
|
||
cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
|
||
out := new(HeartbeatResponse)
|
||
err := c.cc.Invoke(ctx, AgentService_Heartbeat_FullMethodName, in, out, cOpts...)
|
||
if err != nil {
|
||
return nil, err
|
||
}
|
||
return out, nil
|
||
}
|
||
|
||
func (c *agentServiceClient) Subscribe(ctx context.Context, in *SubscribeRequest, opts ...grpc.CallOption) (grpc.ServerStreamingClient[Command], error) {
|
||
cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
|
||
stream, err := c.cc.NewStream(ctx, &AgentService_ServiceDesc.Streams[0], AgentService_Subscribe_FullMethodName, cOpts...)
|
||
if err != nil {
|
||
return nil, err
|
||
}
|
||
x := &grpc.GenericClientStream[SubscribeRequest, Command]{ClientStream: stream}
|
||
if err := x.ClientStream.SendMsg(in); err != nil {
|
||
return nil, err
|
||
}
|
||
if err := x.ClientStream.CloseSend(); err != nil {
|
||
return nil, err
|
||
}
|
||
return x, nil
|
||
}
|
||
|
||
// This type alias is provided for backwards compatibility with existing code that references the prior non-generic stream type by name.
|
||
type AgentService_SubscribeClient = grpc.ServerStreamingClient[Command]
|
||
|
||
func (c *agentServiceClient) Ack(ctx context.Context, in *AckRequest, opts ...grpc.CallOption) (*AckResponse, error) {
|
||
cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
|
||
out := new(AckResponse)
|
||
err := c.cc.Invoke(ctx, AgentService_Ack_FullMethodName, in, out, cOpts...)
|
||
if err != nil {
|
||
return nil, err
|
||
}
|
||
return out, nil
|
||
}
|
||
|
||
func (c *agentServiceClient) ReportUsage(ctx context.Context, in *ReportUsageRequest, opts ...grpc.CallOption) (*ReportUsageResponse, error) {
|
||
cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
|
||
out := new(ReportUsageResponse)
|
||
err := c.cc.Invoke(ctx, AgentService_ReportUsage_FullMethodName, in, out, cOpts...)
|
||
if err != nil {
|
||
return nil, err
|
||
}
|
||
return out, nil
|
||
}
|
||
|
||
// AgentServiceServer is the server API for AgentService service.
|
||
// All implementations should embed UnimplementedAgentServiceServer
|
||
// for forward compatibility.
|
||
//
|
||
// AgentService 是控制面暴露给 Agent 的唯一 gRPC 接口。
|
||
// 连接方向：Agent 主动拨号控制面。
|
||
// 除 Enroll 外，所有 RPC 均需通过 mTLS 客户端证书鉴权。
|
||
type AgentServiceServer interface {
|
||
// Enroll 供新节点申请证书。唯一不要求 mTLS 客户端证书的入口。
|
||
// Agent 提交 bootstrap_token（云初始化注入）与 CSR，控制面签发短期证书。
|
||
Enroll(context.Context, *EnrollRequest) (*EnrollResponse, error)
|
||
// Register 是 mTLS 建立后的首次调用，返回该节点的全量配置快照。
|
||
// ConfigSnapshot 直接作为响应类型（非 RegisterResponse），是有意设计——快照兼用于
|
||
// ApplyConfig 下发，避免重复定义。buf:lint:ignore 声明如下。
|
||
// buf:lint:ignore RPC_RESPONSE_STANDARD_NAME
|
||
Register(context.Context, *RegisterRequest) (*ConfigSnapshot, error)
|
||
// Heartbeat 由 Agent 每 30 秒发送一次，上报实时负载并与控制面对账配置版本。
|
||
// 若 need_full_resync == true，Agent 应主动重新调用 Register。
|
||
Heartbeat(context.Context, *HeartbeatRequest) (*HeartbeatResponse, error)
|
||
// Subscribe 建立控制面 → Agent 的服务端流，用于下发 Command。
|
||
// Agent 重连时携带 last_command_id，控制面补发缺失命令（at-least-once 语义）。
|
||
// Command 直接作为流元素类型（非 SubscribeResponse），是有意设计——下游消费者
|
||
// 直接操作 Command，无需额外包装。buf:lint:ignore 声明如下。
|
||
// buf:lint:ignore RPC_RESPONSE_STANDARD_NAME
|
||
Subscribe(*SubscribeRequest, grpc.ServerStreamingServer[Command]) error
|
||
// Ack 用于 Agent 向控制面回执命令的执行结果。
|
||
Ack(context.Context, *AckRequest) (*AckResponse, error)
|
||
// ReportUsage 上报各数据通道的流量用量，供计费/限速使用。
|
||
// 红线：items 中只含 dp_uuid 与字节/分钟计数，不含目的地址或 DNS 字段。
|
||
ReportUsage(context.Context, *ReportUsageRequest) (*ReportUsageResponse, error)
|
||
}
|
||
|
||
// UnimplementedAgentServiceServer should be embedded to have
|
||
// forward compatible implementations.
|
||
//
|
||
// NOTE: this should be embedded by value instead of pointer to avoid a nil
|
||
// pointer dereference when methods are called.
|
||
type UnimplementedAgentServiceServer struct{}
|
||
|
||
func (UnimplementedAgentServiceServer) Enroll(context.Context, *EnrollRequest) (*EnrollResponse, error) {
|
||
return nil, status.Errorf(codes.Unimplemented, "method Enroll not implemented")
|
||
}
|
||
func (UnimplementedAgentServiceServer) Register(context.Context, *RegisterRequest) (*ConfigSnapshot, error) {
|
||
return nil, status.Errorf(codes.Unimplemented, "method Register not implemented")
|
||
}
|
||
func (UnimplementedAgentServiceServer) Heartbeat(context.Context, *HeartbeatRequest) (*HeartbeatResponse, error) {
|
||
return nil, status.Errorf(codes.Unimplemented, "method Heartbeat not implemented")
|
||
}
|
||
func (UnimplementedAgentServiceServer) Subscribe(*SubscribeRequest, grpc.ServerStreamingServer[Command]) error {
|
||
return status.Errorf(codes.Unimplemented, "method Subscribe not implemented")
|
||
}
|
||
func (UnimplementedAgentServiceServer) Ack(context.Context, *AckRequest) (*AckResponse, error) {
|
||
return nil, status.Errorf(codes.Unimplemented, "method Ack not implemented")
|
||
}
|
||
func (UnimplementedAgentServiceServer) ReportUsage(context.Context, *ReportUsageRequest) (*ReportUsageResponse, error) {
|
||
return nil, status.Errorf(codes.Unimplemented, "method ReportUsage not implemented")
|
||
}
|
||
func (UnimplementedAgentServiceServer) testEmbeddedByValue() {}
|
||
|
||
// UnsafeAgentServiceServer may be embedded to opt out of forward compatibility for this service.
|
||
// Use of this interface is not recommended, as added methods to AgentServiceServer will
|
||
// result in compilation errors.
|
||
type UnsafeAgentServiceServer interface {
|
||
mustEmbedUnimplementedAgentServiceServer()
|
||
}
|
||
|
||
func RegisterAgentServiceServer(s grpc.ServiceRegistrar, srv AgentServiceServer) {
|
||
// If the following call pancis, it indicates UnimplementedAgentServiceServer was
|
||
// embedded by pointer and is nil. This will cause panics if an
|
||
// unimplemented method is ever invoked, so we test this at initialization
|
||
// time to prevent it from happening at runtime later due to I/O.
|
||
if t, ok := srv.(interface{ testEmbeddedByValue() }); ok {
|
||
t.testEmbeddedByValue()
|
||
}
|
||
s.RegisterService(&AgentService_ServiceDesc, srv)
|
||
}
|
||
|
||
func _AgentService_Enroll_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
|
||
in := new(EnrollRequest)
|
||
if err := dec(in); err != nil {
|
||
return nil, err
|
||
}
|
||
if interceptor == nil {
|
||
return srv.(AgentServiceServer).Enroll(ctx, in)
|
||
}
|
||
info := &grpc.UnaryServerInfo{
|
||
Server: srv,
|
||
FullMethod: AgentService_Enroll_FullMethodName,
|
||
}
|
||
handler := func(ctx context.Context, req interface{}) (interface{}, error) {
|
||
return srv.(AgentServiceServer).Enroll(ctx, req.(*EnrollRequest))
|
||
}
|
||
return interceptor(ctx, in, info, handler)
|
||
}
|
||
|
||
func _AgentService_Register_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
|
||
in := new(RegisterRequest)
|
||
if err := dec(in); err != nil {
|
||
return nil, err
|
||
}
|
||
if interceptor == nil {
|
||
return srv.(AgentServiceServer).Register(ctx, in)
|
||
}
|
||
info := &grpc.UnaryServerInfo{
|
||
Server: srv,
|
||
FullMethod: AgentService_Register_FullMethodName,
|
||
}
|
||
handler := func(ctx context.Context, req interface{}) (interface{}, error) {
|
||
return srv.(AgentServiceServer).Register(ctx, req.(*RegisterRequest))
|
||
}
|
||
return interceptor(ctx, in, info, handler)
|
||
}
|
||
|
||
func _AgentService_Heartbeat_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
|
||
in := new(HeartbeatRequest)
|
||
if err := dec(in); err != nil {
|
||
return nil, err
|
||
}
|
||
if interceptor == nil {
|
||
return srv.(AgentServiceServer).Heartbeat(ctx, in)
|
||
}
|
||
info := &grpc.UnaryServerInfo{
|
||
Server: srv,
|
||
FullMethod: AgentService_Heartbeat_FullMethodName,
|
||
}
|
||
handler := func(ctx context.Context, req interface{}) (interface{}, error) {
|
||
return srv.(AgentServiceServer).Heartbeat(ctx, req.(*HeartbeatRequest))
|
||
}
|
||
return interceptor(ctx, in, info, handler)
|
||
}
|
||
|
||
func _AgentService_Subscribe_Handler(srv interface{}, stream grpc.ServerStream) error {
|
||
m := new(SubscribeRequest)
|
||
if err := stream.RecvMsg(m); err != nil {
|
||
return err
|
||
}
|
||
return srv.(AgentServiceServer).Subscribe(m, &grpc.GenericServerStream[SubscribeRequest, Command]{ServerStream: stream})
|
||
}
|
||
|
||
// This type alias is provided for backwards compatibility with existing code that references the prior non-generic stream type by name.
|
||
type AgentService_SubscribeServer = grpc.ServerStreamingServer[Command]
|
||
|
||
func _AgentService_Ack_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
|
||
in := new(AckRequest)
|
||
if err := dec(in); err != nil {
|
||
return nil, err
|
||
}
|
||
if interceptor == nil {
|
||
return srv.(AgentServiceServer).Ack(ctx, in)
|
||
}
|
||
info := &grpc.UnaryServerInfo{
|
||
Server: srv,
|
||
FullMethod: AgentService_Ack_FullMethodName,
|
||
}
|
||
handler := func(ctx context.Context, req interface{}) (interface{}, error) {
|
||
return srv.(AgentServiceServer).Ack(ctx, req.(*AckRequest))
|
||
}
|
||
return interceptor(ctx, in, info, handler)
|
||
}
|
||
|
||
func _AgentService_ReportUsage_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
|
||
in := new(ReportUsageRequest)
|
||
if err := dec(in); err != nil {
|
||
return nil, err
|
||
}
|
||
if interceptor == nil {
|
||
return srv.(AgentServiceServer).ReportUsage(ctx, in)
|
||
}
|
||
info := &grpc.UnaryServerInfo{
|
||
Server: srv,
|
||
FullMethod: AgentService_ReportUsage_FullMethodName,
|
||
}
|
||
handler := func(ctx context.Context, req interface{}) (interface{}, error) {
|
||
return srv.(AgentServiceServer).ReportUsage(ctx, req.(*ReportUsageRequest))
|
||
}
|
||
return interceptor(ctx, in, info, handler)
|
||
}
|
||
|
||
// AgentService_ServiceDesc is the grpc.ServiceDesc for AgentService service.
|
||
// It's only intended for direct use with grpc.RegisterService,
|
||
// and not to be introspected or modified (even as a copy)
|
||
var AgentService_ServiceDesc = grpc.ServiceDesc{
|
||
ServiceName: "pangolin.agent.v1.AgentService",
|
||
HandlerType: (*AgentServiceServer)(nil),
|
||
Methods: []grpc.MethodDesc{
|
||
{
|
||
MethodName: "Enroll",
|
||
Handler: _AgentService_Enroll_Handler,
|
||
},
|
||
{
|
||
MethodName: "Register",
|
||
Handler: _AgentService_Register_Handler,
|
||
},
|
||
{
|
||
MethodName: "Heartbeat",
|
||
Handler: _AgentService_Heartbeat_Handler,
|
||
},
|
||
{
|
||
MethodName: "Ack",
|
||
Handler: _AgentService_Ack_Handler,
|
||
},
|
||
{
|
||
MethodName: "ReportUsage",
|
||
Handler: _AgentService_ReportUsage_Handler,
|
||
},
|
||
},
|
||
Streams: []grpc.StreamDesc{
|
||
{
|
||
StreamName: "Subscribe",
|
||
Handler: _AgentService_Subscribe_Handler,
|
||
ServerStreams: true,
|
||
},
|
||
},
|
||
Metadata: "pangolin/agent/v1/agent.proto",
|
||
}
|