source

package
v0.2.0 Latest Latest
Warning

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

Go to latest
Published: Aug 26, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package source 负责已发布 workflow 的来源协议和默认加载实现。

它包含控制面 HTTP 拉取、bootstrap 轮询缓存、内存 workflow loader 和 source factory。 本包不执行 workflow,也不依赖 plan 的运行入口;plan 根包只组合 source、planner 和 runtime。

Index

Constants

View Source
const (
	// SourceTypeAdmin 表示直接通过 flowlink-admin worker pull 接口按需拉取 workflow。
	SourceTypeAdmin = "admin"
	// SourceTypePollingAdmin 表示在 admin 拉取之上启用本地 bootstrap 轮询缓存。
	SourceTypePollingAdmin = "polling_admin"
	// SourceTypeMemory 表示从内存中的已发布 workflow 集合读取。
	SourceTypeMemory = "memory"
)
View Source
const WorkerTokenHeader = "X-FlowLink-Worker-Token"

WorkerTokenHeader 是 worker pull 接口使用的认证请求头。

Variables

View Source
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")
)
View Source
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")
)
View Source
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

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

Status 返回适合健康检查接口展示的轮询和缓存元数据。

func (*PollingWorkflowLoader) Sync

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

type ResolverFunc func(ctx context.Context, msg adapter.Message) (*PublishedWorkflowRef, error)

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。

func (*SourceConfig) Initial

func (c *SourceConfig) Initial()

Initial 补齐 workflow 来源默认值。

type WorkerBootstrap

type WorkerBootstrap = workerpull.WorkerBootstrap

WorkerBootstrap 是控制面返回给 worker 的发布版本清单。

func CloneWorkerBootstrap

func CloneWorkerBootstrap(value *WorkerBootstrap) *WorkerBootstrap

CloneWorkerBootstrap 返回 bootstrap 响应的防御性副本。

type WorkerHTTPClient

type WorkerHTTPClient struct {
	BaseURL    string
	Token      string
	HTTPClient *http.Client
}

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。

Jump to

Keyboard shortcuts

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