invocation

type Authorizer interface {
	Authorize(ctx context.Context, input AuthzContext) error
}

type AuthzContext struct {
	// Service 表示目标服务身份。
	Service ServiceRef `json:"service"`
	// FullMethod 表示完整 gRPC 方法，例如 /acme.user.v1.UserService/GetUser。
	FullMethod string `json:"full_method"`
	// TraceID 表示链路 ID。
	TraceId string `json:"trace_id"`
	// Caller 表示调用方身份。
	Caller Caller `json:"caller"`
	// Metadata 表示构造判定时附带的完整 metadata 副本。
	Metadata metadata.MD `json:"-"`
}

type Caller struct {
	// UserId 表示当前用户身份，可为空。
	UserId string `json:"user_id"`
	// AppId 表示当前应用身份，可为空。
	AppId string `json:"app_id"`
	// TenantId 表示当前租户身份，可为空。
	TenantId string `json:"tenant_id"`
	// OrgIds 表示当前组织范围，可为空。
	OrgIds []string `json:"org_ids"`
	// RoleIds 表示当前角色范围，可为空。
	RoleIds []string `json:"role_ids"`
}

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

type ConnectionManagerOptions struct {
	// Locator 用于把 ServiceRef 解析为最终 Target。
	Locator Locator
	// DialFunc 用于创建新的 grpc.ClientConn。
	// 若为空，则使用默认拨号实现。
	DialFunc DialFunc
	// DialOptions 表示创建 grpc.ClientConn 时使用的附加选项。
	DialOptions []grpc.DialOption
}

type DialFunc func(ctx context.Context, target Target, options []grpc.DialOption) (*grpc.ClientConn, error)

type Dialer interface {
	Dial(ctx context.Context, ref ServiceRef) (*grpc.ClientConn, error)
	Close() error
}

type InvocationContext struct {
	// TraceId 表示当前调用使用的链路 ID。
	TraceId string `json:"trace_id"`
	// Caller 表示调用者身份。
	Caller Caller `json:"caller"`
	// Metadata 表示调用方额外附带的 metadata。
	// 这里允许业务侧做补充，但核心库仍会统一注入标准字段。
	Metadata metadata.MD `json:"-"`
	// Timeout 表示本次调用的超时时间。
	Timeout time.Duration `json:"timeout"`
}

type InvokeOption func(*InvokeOptions)

type InvokeOptions struct {
	// InvocationContext 表示本次调用要附带的统一上下文。
	InvocationContext InvocationContext
	// CallOptions 表示附加的 gRPC CallOption。
	CallOptions []grpc.CallOption
}

type Invoker interface {
	Invoke(ctx context.Context, ref ServiceRef, method string, req any, resp any, options ...InvokeOption) error
}

type Locator interface {
	Resolve(ctx context.Context, ref ServiceRef) (Target, error)
}

type ServiceEndpoint struct {
	// Address 表示实例地址，通常是 ip:port 或 host:port。
	Address string `json:"address"`
	// Weight 表示实例权重。
	Weight int `json:"weight"`
	// Healthy 表示实例当前健康状态。
	Healthy bool `json:"healthy"`
	// Meta 表示实例附带的轻量元信息，例如标签、版本、可用区等。
	Meta map[string]string `json:"meta"`
}

type ServiceRef struct {
	// Service 表示目标服务名。
	Service string `json:"service"`
	// Namespace 表示目标命名空间。
	// 在 K8s 主路径下，最终 DNS 主要依赖 service + namespace 组合生成。
	Namespace string `json:"namespace"`
	// Env 表示逻辑环境。
	// 它更适合参与平台治理、配置域和策略域选择，而不一定直接进入 DNS。
	Env string `json:"env"`
	// Port 表示可选端口覆盖项。
	// 大多数场景建议由核心库使用默认端口补齐；只有个别服务端口特殊时才显式设置。
	Port uint16 `json:"port"`
}

type StaticLocator struct {
	// Options 控制 target 的构造方式，例如默认端口、集群域和 resolver scheme。
	Options TargetOptions
}

type Target struct {
	// ResolverScheme 表示 gRPC resolver scheme，例如 dns。
	ResolverScheme string `json:"resolver_scheme"`
	// Host 表示目标主机名。
	Host string `json:"host"`
	// Port 表示目标端口。
	Port uint16 `json:"port"`
}

type TargetOptions struct {
	// DefaultPort 表示默认 gRPC 端口。
	// 当 ServiceRef.Port 为空时，会使用该字段补齐。
	DefaultPort uint16
	// ClusterDomain 表示集群域，默认值为 svc.cluster.local。
	ClusterDomain string
	// ResolverScheme 表示 gRPC resolver scheme，默认值为 dns。
	ResolverScheme string
}

type UnaryInvokeFunc func(ctx context.Context, conn *grpc.ClientConn, method string, req any, resp any, options ...grpc.CallOption) error

type UnaryInvoker struct {
	// Dialer 负责连接获取与复用。
	Dialer Dialer
	// Authorizer 是可选依赖；若为空，则跳过 Authz 预检查。
	Authorizer Authorizer
	// InvokeFunc 是可选依赖；若为空，则默认调用 grpc.ClientConn.Invoke。
	InvokeFunc UnaryInvokeFunc
}