jobs

package
v0.0.0-...-e12325a Latest Latest
Warning

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

Go to latest
Published: Nov 15, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Index

Constants

View Source
const (
	ScheduleIdentityCleanupSessions         = "identity.cleanup_sessions"
	ScheduleAttachmentsCleanupOrphans       = "attachments.cleanup_orphans"
	ScheduleAttachmentsReconcileCompression = "attachments.reconcile_compression"
	// ScheduleAuditCleanupEvents 清理过期 audit_events(F1.4 保留期 job)。
	ScheduleAuditCleanupEvents = "audit.cleanup_events"
	// ScheduleForumAutoLockIdle 按站点 autoLockIdleDays 锁定闲置主题。
	ScheduleForumAutoLockIdle = "forum.auto_lock_idle"
	// ScheduleForumBookmarkReminders 扫描到期收藏提醒并发出通知(每分钟)。
	ScheduleForumBookmarkReminders = "forum.bookmark_reminders"
	// ScheduleForumFlushViewCounts 将 Redis 浏览增量刷入 topics.view_count / hot_score。
	ScheduleForumFlushViewCounts = "forum.flush_view_counts"
	// ScheduleSearchReconcile 增量修复当前搜索 provider 的漏建、过期和幽灵文档。
	ScheduleSearchReconcile = "search.reconcile"
	// ScheduleExtensionsFinalizeUninstallCleanup 周期收敛「台账已 succeeded 但
	// tombstone 仍 pending」的卸载物理清理;仅 embed worker 注册执行器。
	ScheduleExtensionsFinalizeUninstallCleanup = "extensions.finalize_uninstall_cleanup"
	// ScheduleTrustLevelsSweep 每日按账本陈旧度重算信任等级(M4b-2)。
	//
	// 它兜住的是**没有活动事件**的那些等级变化:角色变更(identity.role 规则)、
	// OAuth 解绑(identity.oauth_link 规则)、徽章收回(badge.owned 规则)——
	// 这些都不经过 6 个活动触发点,只有按账本 computed_at 兜底才看得见。
	ScheduleTrustLevelsSweep = "trustlevels.sweep"
)

核心 schedule 稳定 ID。新增维护任务时先加常量与 CoreScheduleDefinitions,再在 bootstrap 注入 Constructor。

View Source
const (
	PluginJobRetryNone        = "none"
	PluginJobRetryBounded     = "bounded"
	PluginJobRetryExponential = "exponential"

	PluginJobDefaultConcurrencyLimit = 4
	PluginJobDefaultMaxAttempts      = 5
	PluginJobDefaultRetryDelay       = 30 * time.Second
)
View Source
const (
	PluginJobQueueDefault = "default"
	PluginJobQueueAI      = "ai"
)

插件可声明的队列名与 River 队列名的映射。清单侧的封闭集合在这里落地: 只有 default 与 ai 两条道,其余取值一律回到 default,绝不因为一个笔误把 插件任务塞进 Core 自己的关键队列。

View Source
const (
	PluginJobReasonExactMatch        = "plugin_job.contract_exact"
	PluginJobReasonSourceCompatible  = "plugin_job.source_runtime_compatible"
	PluginJobReasonMigrationDeclared = "plugin_job.migration_declared"
	PluginJobReasonIncompatible      = "plugin_job.contract_incompatible"
	PluginJobReasonEnvelopeInvalid   = "plugin_job.envelope_invalid"
	PluginJobReasonTrustGrantStale   = "plugin_job.trust_grant_stale"
	PluginJobReasonRuntimeChanged    = "plugin_job.runtime_changed"
	PluginJobReasonRunningMigration  = "plugin_job.running_migration_unsafe"
	PluginJobReasonMigratorMissing   = "plugin_job.payload_migrator_missing"
	PluginJobReasonStateUnknown      = "plugin_job.state_unknown"
	PluginJobReasonTargetRemoved     = "plugin_job.target_removed"
	PluginJobReasonJobUnknown        = "plugin_job.unknown"
)
View Source
const (
	QueueCritical      = "critical"
	QueueDefault       = river.QueueDefault
	QueueSearch        = "search"
	QueueMail          = "mail"
	QueueNotifications = "notifications"
	QueueMaintenance   = "maintenance"
	// QueueAI 承载 AI 生成任务。它单独成队是因为这类任务慢(秒级)且失败模式
	// 与其它队列不同:放共享队列会占用工作槽,拖住邮件与通知投递。
	QueueAI = "ai"
)
View Source
const PluginJobEnvelopeVersion = 1
View Source
const PluginScheduleTriggerKind = "extension.plugin_schedule_trigger"

Variables

View Source
var (
	ErrPluginScheduleInvalid      = errors.New("plugin schedule declaration is invalid")
	ErrPluginScheduleRuntimeStale = errors.New("plugin schedule runtime is stale")
	ErrPluginScheduleDraining     = errors.New("plugin schedule runtime is draining")
	ErrPluginScheduleNotDeclared  = errors.New("plugin schedule is not declared")
)
View Source
var ErrPluginJobRuntimeStale = errors.New("plugin job runtime contract is stale")

Functions

func FormatScheduleEnabled

func FormatScheduleEnabled(enabled bool) string

FormatScheduleEnabled 写入 web_options 的规范化值。

func ParseScheduleEnabled

func ParseScheduleEnabled(value string, present bool) bool

ParseScheduleEnabled 解析 option 值;空/缺失视为 true。

func QueueForPluginDeclaration

func QueueForPluginDeclaration(declared string) string

QueueForPluginDeclaration 把清单声明的队列映射为实际 River 队列。

func ScheduleEnabledOptionName

func ScheduleEnabledOptionName(scheduleID string) string

ScheduleEnabledOptionName 返回某条 schedule 在 web_options 中的启用开关键。 缺失时视为启用(与 CoreScheduleDefinitions 默认 Enabled=true 一致)。

func SplitVersionedSchema

func SplitVersionedSchema(reference string) (schemaID, version string, ok bool)

SplitVersionedSchema separates a manifest reference such as demo.payload@1.

func Start

func Start(ctx context.Context, client *Client) error

func Stop

func Stop(ctx context.Context, client *Client) error

func ValidateScheduleID

func ValidateScheduleID(id string) error

ValidateScheduleID 校验 schedule id 形态(防路径注入进 option name)。

Types

type Client

type Client = river.Client[pgx.Tx]

func NewClient

func NewClient(pool *pgxpool.Pool, cfg Config, workers *river.Workers) (*Client, error)

func NewClientWithPeriodic

func NewClientWithPeriodic(pool *pgxpool.Pool, cfg Config, workers *river.Workers, periodicJobs []*river.PeriodicJob) (*Client, error)

NewClientWithPeriodic 创建支持周期任务(PeriodicJobs)的 worker client。 periodicJobs 为 nil/空时退化为普通 NewClient 行为(向后兼容)。 周期任务不经过队列调度,由 River 按 cron 周期触发;需在 worker 进程(非 insert-only)注册。

func NewInsertOnlyClient

func NewInsertOnlyClient(pool *pgxpool.Pool, _ Config) (*Client, error)

type Config

type Config struct {
	CriticalWorkers      int
	DefaultWorkers       int
	SearchWorkers        int
	MailWorkers          int
	NotificationsWorkers int
	MaintenanceWorkers   int
	// AIWorkers 是 AI 生成队列的并发上限。调用慢且会命中供应商限流,
	// 因此默认值远低于其它队列。
	AIWorkers int
}

func FromAppConfig

func FromAppConfig(cfg config.Config) Config

func (Config) RiverQueues

func (cfg Config) RiverQueues() map[string]river.QueueConfig

type Dispatcher

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

func NewDispatcher

func NewDispatcher(client RiverClient) *Dispatcher

func (*Dispatcher) Enqueue

func (*Dispatcher) EnqueueMany

func (d *Dispatcher) EnqueueMany(ctx context.Context, argsList []river.JobArgs, opts EnqueueOptions) ([]*rivertype.JobInsertResult, error)

EnqueueMany 批量入队同质 job(共享同一 EnqueueOptions)。 内部用 River InsertMany 单次批量 INSERT,比循环单条快一个数量级, 适合重建索引这类一次性入队成千上万个 job 的场景。 River 的 Unique ByArgs 会自动去重,重复入队安全幂等。

func (*Dispatcher) EnqueueTx

func (d *Dispatcher) EnqueueTx(ctx context.Context, tx pgx.Tx, args river.JobArgs, opts EnqueueOptions) (*rivertype.JobInsertResult, error)

type EnqueueOptions

type EnqueueOptions struct {
	Queue       string
	MaxAttempts int
	ScheduledAt time.Time
	Unique      river.UniqueOpts
}

func (EnqueueOptions) RiverInsertOpts

func (opts EnqueueOptions) RiverInsertOpts() *river.InsertOpts

type PluginJobAction

type PluginJobAction string
const (
	PluginJobExecute PluginJobAction = "execute"
	PluginJobDrain   PluginJobAction = "drain"
	PluginJobMigrate PluginJobAction = "migrate"
	PluginJobCancel  PluginJobAction = "cancel"
)

type PluginJobConcurrencyLimiter

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

PluginJobConcurrencyLimiter enforces the immutable per-artifact job policy before plugin code starts. Keys include the artifact digest so an upgrade cannot reuse a channel with a different declared capacity.

func (*PluginJobConcurrencyLimiter) Acquire

func (l *PluginJobConcurrencyLimiter) Acquire(ctx context.Context, contract PluginJobContract) (func(), error)

type PluginJobContract

type PluginJobContract struct {
	ExtensionID          string `json:"extensionId"`
	ExtensionVersion     string `json:"extensionVersion"`
	ArtifactDigest       string `json:"artifactDigest"`
	JobName              string `json:"jobName"`
	JobContract          string `json:"jobContractVersion"`
	PayloadSchemaID      string `json:"payloadSchemaId"`
	PayloadSchemaVersion string `json:"payloadSchemaVersion"`
	RetryPolicy          string `json:"retryPolicy,omitempty"`
	MaxAttempts          int    `json:"maxAttempts,omitempty"`
	RetryDelaySeconds    int    `json:"retryDelaySeconds,omitempty"`
	ConcurrencyLimit     int    `json:"concurrencyLimit,omitempty"`
	// Queue 是清单声明的队列名("default"/"ai",空值等同 default)。
	// 它只影响任务落在哪条通道,不改变准入、租约与重试语义。
	Queue string `json:"queue,omitempty"`
}

PluginJobContract identifies the immutable code and data contract that may consume one queued plugin job. Runtime epochs and process instances are intentionally excluded because a durable job may outlive either value.

func (PluginJobContract) Equal

func (c PluginJobContract) Equal(other PluginJobContract) bool

func (PluginJobContract) Normalized

func (c PluginJobContract) Normalized() PluginJobContract

Normalized pins legacy rows to the V3 recommended execution policy. Policy fields are part of exact contract equality so an undeclared policy change cannot silently alter already queued work.

func (PluginJobContract) Valid

func (c PluginJobContract) Valid() bool

type PluginJobDecision

type PluginJobDecision struct {
	Action      PluginJobAction
	Reason      string
	MigrationID string
}

func DecidePluginJobExecution

func DecidePluginJobExecution(queued, target PluginJobContract, migrations []PluginJobMigration) PluginJobDecision

DecidePluginJobExecution allows execution only for an exact immutable contract. Payload migration is a separately declared lifecycle operation.

func DecidePluginJobUpgrade

func DecidePluginJobUpgrade(input PluginJobUpgrade) PluginJobDecision

DecidePluginJobUpgrade is the inspectable policy used before switching an upgraded runtime: target-compatible jobs execute, source-compatible jobs drain, exact declared migrations migrate, and everything else is cancelled.

type PluginJobInvocation

type PluginJobInvocation struct {
	JobID        int64
	Attempt      int
	Contract     PluginJobContract
	TrustGrantID string
	Payload      map[string]any
	EnqueuedAt   time.Time
}

PluginJobInvocation is the runtime-facing value after River compatibility checks have succeeded.

type PluginJobMigration

type PluginJobMigration struct {
	ID   string
	From PluginJobContract
	To   PluginJobContract
}

type PluginJobUpgrade

type PluginJobUpgrade struct {
	Queued                 PluginJobContract
	Source                 PluginJobContract
	Target                 PluginJobContract
	SourceRuntimeAvailable bool
	Migrations             []PluginJobMigration
}

type PluginScheduleAdmissionRegistry

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

PluginScheduleAdmissionRegistry 让发布、触发 admission 与 drain 共用一把锁。 生命周期可以先 BeginDrain,再 WaitDrain,保证返回后不再出现新的触发写入。

func NewPluginScheduleAdmissionRegistry

func NewPluginScheduleAdmissionRegistry() *PluginScheduleAdmissionRegistry

func (*PluginScheduleAdmissionRegistry) AcquireTrigger

AcquireTrigger 同时校验活动 exact runtime 与 schedule declaration。

func (*PluginScheduleAdmissionRegistry) BeginDrain

BeginDrain 与 AcquireTrigger 线性化;返回后该 exact runtime 不再获得新 lease。

func (*PluginScheduleAdmissionRegistry) BindPeriodicPublisher

func (r *PluginScheduleAdmissionRegistry) BindPeriodicPublisher(publisher *PluginSchedulePeriodicPublisher) error

BindPeriodicPublisher publishes already-active snapshots when a worker's River client becomes available. Each worker process binds its own bundle so leader changes keep the same dynamic catalog.

func (*PluginScheduleAdmissionRegistry) PublishActive

PublishActive 原子发布新实例,并在同一线性化边界关闭旧实例的新触发入口。

func (*PluginScheduleAdmissionRegistry) Snapshot

func (*PluginScheduleAdmissionRegistry) WaitDrain

type PluginScheduleDeclaration

type PluginScheduleDeclaration struct {
	ScheduleID   string
	JobName      string
	JobContract  string
	Cron         string
	Timezone     string
	Contract     PluginJobContract
	TrustGrantID string
}

PluginScheduleDeclaration 是已验证 manifest 发布给宿主调度器的不可变契约。 本 registry 只管理 admission;它不自行创建 cron goroutine 或 River constructor。

type PluginSchedulePeriodicBundle

type PluginSchedulePeriodicBundle interface {
	AddSafely(*river.PeriodicJob) (rivertype.PeriodicJobHandle, error)
	RemoveByID(string) bool
}

type PluginSchedulePeriodicPublisher

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

PluginSchedulePeriodicPublisher owns this process's dynamic River catalog. River elects one leader, but every worker publishes the same exact snapshot so a leadership change cannot restore removed schedules.

func (*PluginSchedulePeriodicPublisher) Remove

func (*PluginSchedulePeriodicPublisher) Replace

type PluginScheduleRuntime

type PluginScheduleRuntime struct {
	Identity  PluginScheduleRuntimeIdentity
	Schedules []PluginScheduleDeclaration
}

type PluginScheduleRuntimeIdentity

type PluginScheduleRuntimeIdentity struct {
	ExtensionID      string
	ExtensionVersion string
	ArtifactDigest   string
	InstanceID       string
}

PluginScheduleRuntimeIdentity 固定触发器归属的 exact runtime artifact。

func (PluginScheduleRuntimeIdentity) Valid

type PluginScheduleSnapshot

type PluginScheduleSnapshot struct {
	Identity       PluginScheduleRuntimeIdentity
	Active         bool
	Draining       bool
	ActiveTriggers int
	Schedules      []PluginScheduleDeclaration
}

type PluginScheduleTriggerArgs

type PluginScheduleTriggerArgs struct {
	ExtensionID      string `json:"extensionId"`
	ExtensionVersion string `json:"extensionVersion"`
	ArtifactDigest   string `json:"artifactDigest"`
	InstanceID       string `json:"instanceId"`
	ScheduleID       string `json:"scheduleId"`
}

PluginScheduleTriggerArgs is Host-owned work. The periodic leader inserts only this exact-runtime marker; its worker acquires schedule admission before inserting the declared plugin job.

func (PluginScheduleTriggerArgs) Identity

func (PluginScheduleTriggerArgs) InsertOpts

func (PluginScheduleTriggerArgs) Kind

type PluginScheduleTriggerLease

type PluginScheduleTriggerLease struct {
	Context context.Context
	// contains filtered or unexported fields
}

func (*PluginScheduleTriggerLease) Release

func (l *PluginScheduleTriggerLease) Release()

type Registrar

type Registrar func(workers *river.Workers) error

type Registry

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

func NewRegistry

func NewRegistry() *Registry

func (*Registry) Add

func (r *Registry) Add(registrar Registrar)

func (*Registry) Build

func (r *Registry) Build() (*river.Workers, error)

func (*Registry) IsEmpty

func (r *Registry) IsEmpty() bool

type RiverClient

type RiverClient interface {
	Insert(ctx context.Context, args river.JobArgs, opts *river.InsertOpts) (*rivertype.JobInsertResult, error)
	InsertTx(ctx context.Context, tx pgx.Tx, args river.JobArgs, opts *river.InsertOpts) (*rivertype.JobInsertResult, error)
	InsertMany(ctx context.Context, params []river.InsertManyParams) ([]*rivertype.JobInsertResult, error)
}

type ScheduleDefinition

type ScheduleDefinition struct {
	// ID 稳定唯一键,例如 "identity.cleanup_sessions"。
	ID string
	// JobKind 对应 River job kind(通常与 Args.Kind() 一致)。
	JobKind string
	// Queue 期望队列名;BuildPeriodicJobs 会写入 InsertOpts(若 Constructor 未自带 opts)。
	Queue string
	// Interval 固定间隔;与 Cron 二选一,F1 仅要求 interval。
	Interval time.Duration
	// Cron 可选 cron 表达式;F1 未实现解析,非空且 Interval==0 时 Build 报错。
	Cron string
	// Owner 归属模块或扩展 id,例如 "identity" / "attachments" / "extensions"。
	Owner string
	// Enabled 目录默认是否启用;worker 仍会注册 PeriodicJob,真正跳过依赖 constructor 读 option。
	Enabled bool
	// Description 运维可读说明(中文优先,与产品文案一致即可)。
	Description string
	// RunOnStart 是否在 worker 启动时立即插入一次(透传 River PeriodicJobOpts)。
	RunOnStart bool
	// Constructor 触发时构造 job args;不得阻塞。仅 worker 进程需要非 nil。
	// 返回 (nil, nil) 时 River 跳过本次插入(用于运行时停用)。
	Constructor river.PeriodicJobConstructor
}

ScheduleDefinition 描述一条平台拥有的周期任务目录项。 River 负责实际触发;本结构是 SForum 的 schedule catalog,供 bootstrap 注册与 admin 展示/运维。 运行时启用状态以 web_options(ScheduleEnabledOptionName)为准;Enabled 字段是目录默认值。 插件不得自行启动 goroutine cron;后续插件 schedule 也须经本 registry 声明。

func CoreScheduleDefinitions

func CoreScheduleDefinitions() []ScheduleDefinition

CoreScheduleDefinitions 返回宿主内置 schedule 目录模板(无 Constructor)。 bootstrap 负责填入 Constructor 后 Register;admin 列表可直接用这些元数据。

func (ScheduleDefinition) View

func (def ScheduleDefinition) View() ScheduleView

type ScheduleRegistry

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

ScheduleRegistry 是进程内 schedule catalog。 新维护任务应 Register 一条定义,而不是在 bootstrap 里散落 NewPeriodicJob。

func NewCoreScheduleRegistry

func NewCoreScheduleRegistry(constructors map[string]river.PeriodicJobConstructor) (*ScheduleRegistry, error)

NewCoreScheduleRegistry 用内置模板构建 registry。 constructors 按 schedule ID 注入;缺失时条目仍进入 catalog,但不生成 River PeriodicJob。

func NewScheduleRegistry

func NewScheduleRegistry() *ScheduleRegistry

func (*ScheduleRegistry) BuildPeriodicJobs

func (r *ScheduleRegistry) BuildPeriodicJobs() ([]*river.PeriodicJob, error)

BuildPeriodicJobs 将 enabled 且带 Constructor 的定义转为 River PeriodicJob。 disabled 或 Constructor==nil 的条目跳过(catalog-only 进程可用)。

func (*ScheduleRegistry) Definitions

func (r *ScheduleRegistry) Definitions() []ScheduleDefinition

Definitions 返回按登记顺序的副本,供 admin / 测试只读遍历。

func (*ScheduleRegistry) Len

func (r *ScheduleRegistry) Len() int

Len 返回已登记条目数(含 disabled)。

func (*ScheduleRegistry) Register

func (r *ScheduleRegistry) Register(def ScheduleDefinition) error

Register 登记一条 schedule。ID 必填且不可重复;JobKind 必填。

func (*ScheduleRegistry) SortedDefinitions

func (r *ScheduleRegistry) SortedDefinitions() []ScheduleDefinition

SortedDefinitions 返回按 ID 排序的副本,便于稳定测试与 OpenAPI 示例。

func (*ScheduleRegistry) Views

func (r *ScheduleRegistry) Views() []ScheduleView

Views 将 registry 投影为稳定 JSON 视图(按登记顺序)。

type ScheduleView

type ScheduleView struct {
	ID              string `json:"id"`
	JobKind         string `json:"jobKind"`
	Queue           string `json:"queue"`
	IntervalSeconds int64  `json:"intervalSeconds,omitempty"`
	Cron            string `json:"cron,omitempty"`
	Owner           string `json:"owner"`
	Enabled         bool   `json:"enabled"`
	Description     string `json:"description"`
	RunOnStart      bool   `json:"runOnStart"`
	// LastRunAt 最近一次该 job kind 入队/执行时间(RFC3339);尚无历史时省略。
	LastRunAt *string `json:"lastRunAt,omitempty"`
	// NextRunAt 粗估下次周期触发时间;停用或无法估算时省略。
	NextRunAt *string `json:"nextRunAt,omitempty"`
}

ScheduleView 是 admin / API 使用的投影(不含 Constructor)。 LastRunAt / NextRunAt 由 Models/Jobs 在列表时按 River 历史与 interval 估算填充。

Jump to

Keyboard shortcuts

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