Documentation
¶
Overview ¶
Package source 负责已发布 workflow 的来源协议和默认加载实现。
它包含控制面 HTTP 拉取、bootstrap 轮询缓存、内存 workflow loader 和 source factory。 本包不执行 workflow,也不依赖 plan 的运行入口;plan 根包只组合 source、planner 和 runtime。
Index ¶
- Constants
- Variables
- func CloneEnvelope(value *core.Envelope) *core.Envelope
- func CloneWorkflow(value *core.Workflow) *core.Workflow
- func RegisterWorkflowSourceFactory(sourceType string, factory WorkflowSourceFactory) error
- func ValidateWorkflowSource(source WorkflowSource) error
- type AdminSourceConfig
- type MemorySourceConfig
- type MemoryWorkflowLoader
- type PollingSourceConfig
- type PollingWorkflowLoader
- func (l *PollingWorkflowLoader) LoadPublished(ctx context.Context, scope ServiceScope, workflowID string, version string) (*core.Workflow, error)
- func (l *PollingWorkflowLoader) PollInterval() time.Duration
- func (l *PollingWorkflowLoader) Scope() ServiceScope
- func (l *PollingWorkflowLoader) Snapshot() *WorkerBootstrap
- func (l *PollingWorkflowLoader) Start(ctx context.Context)
- func (l *PollingWorkflowLoader) Status() PollingWorkflowLoaderStatus
- func (l *PollingWorkflowLoader) Sync(ctx context.Context) (*WorkerBootstrap, error)
- func (l *PollingWorkflowLoader) Validate() error
- type PollingWorkflowLoaderOptions
- type PollingWorkflowLoaderStatus
- type PublishedWorkflowHead
- type PublishedWorkflowRef
- type PublishedWorkflowResolver
- type ResolverFunc
- type ServiceScope
- type SourceConfig
- type WorkerBootstrap
- type WorkerHTTPClient
- func (c *WorkerHTTPClient) Bootstrap(ctx context.Context, scope ServiceScope) (*WorkerBootstrap, error)
- func (c *WorkerHTTPClient) LoadPublished(ctx context.Context, scope ServiceScope, workflowID string, version string) (*core.Workflow, error)
- func (c *WorkerHTTPClient) ReportCapabilities(ctx context.Context, report *workercapability.ReportRequest) error
- func (c *WorkerHTTPClient) Validate() error
- type WorkflowSource
- type WorkflowSourceFactory
Constants ¶
const ( // SourceTypeAdmin 表示直接通过 flowlink-admin worker pull 接口按需拉取 workflow。 SourceTypeAdmin = "admin" // SourceTypePollingAdmin 表示在 admin 拉取之上启用本地 bootstrap 轮询缓存。 SourceTypePollingAdmin = "polling_admin" // SourceTypeMemory 表示从内存中的已发布 workflow 集合读取。 SourceTypeMemory = "memory" )
const WorkerTokenHeader = "X-FlowLink-Worker-Token"
WorkerTokenHeader 是 worker pull 接口使用的认证请求头。
Variables ¶
var ( // ErrWorkflowSourceRequired 表示发布 workflow 执行缺少加载来源。 ErrWorkflowSourceRequired = errors.New("published workflow source is required") // ErrAdminSourceRequired 表示 AdminSourceConfig 缺少控制面地址。 ErrAdminSourceRequired = errors.New("admin base url is required") // ErrWorkflowSourceTypeUnsupported 表示配置中的 workflow 来源类型没有注册工厂。 ErrWorkflowSourceTypeUnsupported = errors.New("workflow source type is unsupported") )
var ( // ErrWorkerRequired 表示 plan worker 调用缺少可用 Worker。 ErrWorkerRequired = errors.New("flowlink worker is required") // ErrWorkerScopeRequired 表示 worker scope 缺少 env 或 workspace 信息。 ErrWorkerScopeRequired = workerpull.ErrScopeRequired // ErrWorkerScopeMismatch 表示启动期 scope 与请求 FlowContext 中的 scope 不一致。 ErrWorkerScopeMismatch = errors.New("worker scope mismatch") // ErrPublishedWorkflowRefRequired 表示缺少发布 workflow 引用。 ErrPublishedWorkflowRefRequired = errors.New("published workflow ref is required") // ErrPublishedWorkflowRefMismatch 表示启动期默认 workflow 与请求中的 workflow 引用不一致。 ErrPublishedWorkflowRefMismatch = errors.New("published workflow ref mismatch") // ErrPublishedWorkflowResolverNeeded 表示处理消息时缺少 workflow 解析器。 ErrPublishedWorkflowResolverNeeded = errors.New("published workflow resolver is required") // ErrWorkflowIDRequired 表示发布 workflow 引用缺少 workflowId。 ErrWorkflowIDRequired = errors.New("workflow id is required") )
var ErrWorkerHTTPClientRequired = errors.New("worker http client is required")
ErrWorkerHTTPClientRequired 表示轮询加载器缺少 HTTP client。
Functions ¶
func CloneEnvelope ¶
func CloneEnvelope(value *core.Envelope) *core.Envelope
CloneEnvelope 返回 envelope 的防御性副本。
func CloneWorkflow ¶
func CloneWorkflow(value *core.Workflow) *core.Workflow
CloneWorkflow 返回 workflow 定义的防御性副本。
func RegisterWorkflowSourceFactory ¶
func RegisterWorkflowSourceFactory(sourceType string, factory WorkflowSourceFactory) error
RegisterWorkflowSourceFactory 注册自定义 workflow 来源类型。
sourceType 会被归一化成小写。重复注册会返回错误,避免一个类型在进程内有多个解释。
func ValidateWorkflowSource ¶
func ValidateWorkflowSource(source WorkflowSource) error
ValidateWorkflowSource 调用 workflow source 自身的可选配置校验。
Types ¶
type AdminSourceConfig ¶
type AdminSourceConfig struct {
// BaseURL 是 flowlink-admin 的 HTTP 基础地址,例如 http://127.0.0.1:18080。
// WorkerHTTPClient 会在它后面拼接 worker pull 路径。
BaseURL string `json:"baseUrl" yaml:"baseUrl"`
// Token 非空时会作为 worker 认证请求头发送。
Token string `json:"token" yaml:"token"`
// HTTPClient 允许调用方注入超时、链路追踪、代理规则或测试客户端。
// 为空时使用 http.DefaultClient。
HTTPClient *http.Client `json:"-" yaml:"-"`
}
AdminSourceConfig 描述 worker 拉取已发布 workflow 定义时使用的控制面地址。
它既可以由宿主服务自己的配置系统填充后传给 ConfigureFromConfig,也可以由 ConfigureFromFile 通过 FlowLink 配置文件读取。BaseURL 为空会被拒绝,因为 Admin 路径必须有明确的 workflow 来源地址。
type MemorySourceConfig ¶
type MemorySourceConfig struct {
Workflows []*core.Workflow `json:"workflows" yaml:"workflows"`
}
MemorySourceConfig 配置内存 workflow 来源。
它主要服务测试、示例和不接控制面的内嵌部署。生产业务如果需要从数据库、 Redis 或配置中心读取 workflow,应注册自己的 SourceFactory。
type MemoryWorkflowLoader ¶
type MemoryWorkflowLoader struct {
// contains filtered or unexported fields
}
MemoryWorkflowLoader 是 WorkflowSource 的内存实现。
它适合测试、演示和由宿主进程直接提供已发布 workflow 定义的内嵌部署。 保存和返回时都会使用防御性副本,避免调用方修改 loader 内部缓存。
func NewMemoryWorkflowLoader ¶
func NewMemoryWorkflowLoader() *MemoryWorkflowLoader
NewMemoryWorkflowLoader 创建空的内存 loader。
func (*MemoryWorkflowLoader) LoadPublished ¶
func (l *MemoryWorkflowLoader) LoadPublished(_ context.Context, scope ServiceScope, workflowID string, version string) (*core.Workflow, error)
LoadPublished 返回匹配 scope、workflowID 和 version 的 workflow。
返回值是副本,校验、planning 或测试可以安全修改它,而不会影响 loader 状态。
func (*MemoryWorkflowLoader) SavePublished ¶
func (l *MemoryWorkflowLoader) SavePublished(workflow *core.Workflow) error
SavePublished 保存一个已发布 workflow 定义。
workflow 必须包含 env、workspace、id 和 version, 因为这些字段共同组成 LoadPublished 使用的已发布 workflow 坐标。
type PollingSourceConfig ¶
type PollingSourceConfig struct {
// Interval 是 bootstrap 轮询周期,例如 30s、1m。
// 为空时使用 PollingWorkflowLoader 的默认周期。
Interval string `json:"interval" yaml:"interval"`
}
PollingSourceConfig 配置 admin 来源外层的本地轮询缓存。
type PollingWorkflowLoader ¶
type PollingWorkflowLoader struct {
// contains filtered or unexported fields
}
PollingWorkflowLoader 在本地维护已发布 workflow 的轻量视图。
它在后台轮询 bootstrap head,但只有 LoadPublished 需要时才拉取完整 workflow 定义。 已拉取的版本会保留在缓存中,因此控制面短暂不可用时,使用已缓存定义的执行不会立刻中断。
func NewPollingWorkflowLoader ¶
func NewPollingWorkflowLoader(opts *PollingWorkflowLoaderOptions) (*PollingWorkflowLoader, error)
NewPollingWorkflowLoader 创建绑定到单个 worker scope 的轮询 loader。
func (*PollingWorkflowLoader) LoadPublished ¶
func (l *PollingWorkflowLoader) LoadPublished(ctx context.Context, scope ServiceScope, workflowID string, version string) (*core.Workflow, error)
LoadPublished 按 scope、workflowID 和 version 加载完整 workflow 定义。
version 为空表示使用当前已知 head。返回前会复制结果,避免调用方修改缓存。 相同 cache key 的并发加载会被合并,保证同一时刻只有一个控制面请求在路上。
func (*PollingWorkflowLoader) PollInterval ¶
func (l *PollingWorkflowLoader) PollInterval() time.Duration
PollInterval 返回实际生效的后台轮询间隔。
func (*PollingWorkflowLoader) Scope ¶
func (l *PollingWorkflowLoader) Scope() ServiceScope
Scope 返回当前 loader 同步的 worker scope。
func (*PollingWorkflowLoader) Snapshot ¶
func (l *PollingWorkflowLoader) Snapshot() *WorkerBootstrap
Snapshot 返回最近一次同步到的 bootstrap head,不访问控制面。
func (*PollingWorkflowLoader) Start ¶
func (l *PollingWorkflowLoader) Start(ctx context.Context)
Start 启动后台 bootstrap 轮询。
调用方通过 ctx 控制停止。Start 会启动 goroutine 并立即返回。
func (*PollingWorkflowLoader) Status ¶
func (l *PollingWorkflowLoader) Status() PollingWorkflowLoaderStatus
Status 返回适合健康检查接口展示的轮询和缓存元数据。
func (*PollingWorkflowLoader) Sync ¶
func (l *PollingWorkflowLoader) Sync(ctx context.Context) (*WorkerBootstrap, error)
Sync 立即同步一次已发布 workflow head。
head 版本变化时,会清理 latest 缓存和新版本缓存 key,使下一次 LoadPublished 拉取新定义。 从 bootstrap 响应中消失的 workflow 也会从本地缓存清理。
func (*PollingWorkflowLoader) Validate ¶
func (l *PollingWorkflowLoader) Validate() error
Validate 校验轮询 loader 启动前必须具备可用的控制面 client。
type PollingWorkflowLoaderOptions ¶
type PollingWorkflowLoaderOptions struct {
// Client 负责访问 flowlink-admin 的 worker pull 接口。
Client *WorkerHTTPClient
// Scope 限定要同步的已发布 workflow head 范围。
Scope ServiceScope
// PollInterval 控制后台 bootstrap 频率;非正值使用包内默认值。
PollInterval time.Duration
}
PollingWorkflowLoaderOptions 配置 PollingWorkflowLoader。
type PollingWorkflowLoaderStatus ¶
type PollingWorkflowLoaderStatus struct {
Scope ServiceScope `json:"scope"`
PollInterval time.Duration `json:"pollInterval"`
WorkflowCount int `json:"workflowCount"`
CachedWorkflowCount int `json:"cachedWorkflowCount"`
LastSyncAt time.Time `json:"lastSyncAt"`
LastSuccessAt time.Time `json:"lastSuccessAt"`
LastError string `json:"lastError,omitempty"`
}
PollingWorkflowLoaderStatus 是轮询和缓存状态的瞬时快照。
type PublishedWorkflowHead ¶
type PublishedWorkflowHead = workerpull.PublishedWorkflowHead
PublishedWorkflowHead 是控制面 bootstrap 返回的已发布 workflow 摘要。
func ClonePublishedWorkflowHead ¶
func ClonePublishedWorkflowHead(value *PublishedWorkflowHead) *PublishedWorkflowHead
ClonePublishedWorkflowHead 返回发布 workflow 摘要的防御性副本。
type PublishedWorkflowRef ¶
type PublishedWorkflowRef struct {
WorkflowID string `json:"workflowId" yaml:"workflowId"`
Version string `json:"version" yaml:"version"`
}
PublishedWorkflowRef 指向一个已发布 workflow 版本。
func ClonePublishedWorkflowRef ¶
func ClonePublishedWorkflowRef(value *PublishedWorkflowRef) *PublishedWorkflowRef
ClonePublishedWorkflowRef 返回发布 workflow 引用的防御性副本。
func (*PublishedWorkflowRef) Validate ¶
func (r *PublishedWorkflowRef) Validate() error
Validate 校验发布 workflow 引用。
type PublishedWorkflowResolver ¶
type PublishedWorkflowResolver interface {
ResolvePublished(ctx context.Context, msg adapter.Message) (*PublishedWorkflowRef, error)
}
PublishedWorkflowResolver 从 adapter 消息解析要执行的发布 workflow。
func StaticResolver ¶
func StaticResolver(workflowID string, version string) PublishedWorkflowResolver
StaticResolver 固定返回同一个 workflowId/version,适合单链路 worker。
type ResolverFunc ¶
ResolverFunc 将普通函数适配为 PublishedWorkflowResolver。
func (ResolverFunc) ResolvePublished ¶
func (fn ResolverFunc) ResolvePublished(ctx context.Context, msg adapter.Message) (*PublishedWorkflowRef, error)
ResolvePublished 调用底层解析函数。
type ServiceScope ¶
type ServiceScope = workerpull.ServiceScope
ServiceScope 是业务 worker 拉取 workflow 时使用的服务范围。
type SourceConfig ¶
type SourceConfig struct {
Type string `json:"type" yaml:"type"`
Admin AdminSourceConfig `json:"admin" yaml:"admin"`
Polling PollingSourceConfig `json:"polling" yaml:"polling"`
Memory MemorySourceConfig `json:"memory" yaml:"memory"`
Options map[string]interface{} `json:"options,omitempty" yaml:"options,omitempty"`
}
SourceConfig 描述已发布 workflow 来源。
Type 决定使用哪个来源工厂。内置值包括 admin、polling_admin 和 memory。 业务也可以通过 RegisterWorkflowSourceFactory 注册自己的 type。
type WorkerBootstrap ¶
type WorkerBootstrap = workerpull.WorkerBootstrap
WorkerBootstrap 是控制面返回给 worker 的发布版本清单。
func CloneWorkerBootstrap ¶
func CloneWorkerBootstrap(value *WorkerBootstrap) *WorkerBootstrap
CloneWorkerBootstrap 返回 bootstrap 响应的防御性副本。
type WorkerHTTPClient ¶
WorkerHTTPClient 是业务 worker 拉取控制面发布 workflow 的轻量 HTTP 客户端。
func (*WorkerHTTPClient) Bootstrap ¶
func (c *WorkerHTTPClient) Bootstrap(ctx context.Context, scope ServiceScope) (*WorkerBootstrap, error)
Bootstrap 拉取指定 scope 下最新发布 workflow 的轻量清单。
func (*WorkerHTTPClient) LoadPublished ¶
func (c *WorkerHTTPClient) LoadPublished(ctx context.Context, scope ServiceScope, workflowID string, version string) (*core.Workflow, error)
LoadPublished 拉取一个完整的已发布 workflow 定义。
func (*WorkerHTTPClient) ReportCapabilities ¶ added in v0.2.0
func (c *WorkerHTTPClient) ReportCapabilities(ctx context.Context, report *workercapability.ReportRequest) error
ReportCapabilities 把当前业务 Worker 的节点目录上报给控制面。
func (*WorkerHTTPClient) Validate ¶
func (c *WorkerHTTPClient) Validate() error
Validate 校验 HTTP 来源是否具备最小可用配置。
type WorkflowSource ¶
type WorkflowSource interface {
LoadPublished(ctx context.Context, scope ServiceScope, workflowID string, version string) (*core.Workflow, error)
}
WorkflowSource 按 scope 和版本坐标提供完整 workflow 定义。
func AdminSource ¶
func AdminSource(baseURL string, token string) WorkflowSource
AdminSource 创建基于 flowlink-admin worker pull 接口的 workflow 来源。
func AdminSourceWithConfig ¶
func AdminSourceWithConfig(config AdminSourceConfig) WorkflowSource
AdminSourceWithConfig 使用完整配置创建 flowlink-admin workflow 来源。
func BuildWorkflowSource ¶
func BuildWorkflowSource(ctx context.Context, scope ServiceScope, config SourceConfig) (WorkflowSource, error)
BuildWorkflowSource 根据 SourceConfig 创建已发布 workflow 来源。
type WorkflowSourceFactory ¶
type WorkflowSourceFactory func(ctx context.Context, scope ServiceScope, config SourceConfig) (WorkflowSource, error)
WorkflowSourceFactory 根据启动配置创建 workflow 来源。
工厂只负责启动期依赖组装,不应该读取或修改单次请求的 FlowContext。