@longzai-intelligence-git/fetch-scheduler 0.1.7

package/README.md

@@ -0,0 +1,15 @@
+# @longzai-intelligence-git/fetch-scheduler
+
+Longzai Intelligence Git 的多仓拉取调度引擎。
+
+## 简介
+
+治理巨量仓库远端更新的调度关注点：以分档 TTL 与每仓抖动错峰决定何时对哪些仓库发起 fetch，受控并发池与单仓超时保障执行不击穿磁盘与远端，连续失败按阶梯退避隔离不健康仓库。仓库候选装载、拉取执行、状态持久化与事件上报全部经依赖注入回调交由宿主承载，引擎自身零落盘。
+
+## 能力
+
+- 分档调度：活跃、近期、休眠三档 TTL 与每仓抖动错峰
+- 并发限流：受控并发池与单仓拉取超时保护
+- 失败退避：连续失败阶梯退避与成功复位
+- 纯规划层：选仓判定为注入时钟与随机源的纯函数，零定时器可测
+- 宿主无关：候选、执行器、状态存储与事件全部经注入回调

package/dist/index.d.ts

@@ -0,0 +1,427 @@
+//#region src/types.d.ts
+/**
+ * fetch 调度引擎的类型契约
+ *
+ * 承载分档拉取调度的全部类型定义：候选、退避状态、选项与事件
+ * 宿主经这些类型注入仓库候选并接收调度事件，引擎不定义持久化与执行细节
+ */
+/**
+ * 时钟源函数，返回毫秒时间戳
+ */
+type ClockSource = () => number;
+/**
+ * 随机源函数，返回零到一区间的浮点数
+ */
+type RandomSource = () => number;
+/**
+ * 拉取分档标识
+ *
+ * `active` 活跃档，`recent` 近期档，`dormant` 休眠档
+ */
+type FetchTier = 'active' | 'recent' | 'dormant';
+/**
+ * 单仓失败退避状态
+ *
+ * 由引擎在拉取失败时构造并经 `onFetchStateChange` 交宿主持久化
+ * 拉取成功时引擎回传 `null` 表示清除退避状态
+ */
+type FetchFailureState = {
+  /**
+   * 连续失败次数，成功拉取后复位为清除状态
+   */
+  readonly consecutiveFailures: number;
+  /**
+   * 退避截止时刻，毫秒时间戳，到期前该仓被跳过
+   */
+  readonly backoffUntil: number | null;
+  /**
+   * 最近一次失败的错误描述
+   */
+  readonly lastError: string | null;
+};
+/**
+ * 单仓拉取候选
+ *
+ * 由宿主装载并整批提供给引擎，引擎只读不改
+ */
+type FetchCandidate = {
+  /**
+   * 宿主侧仓库标识，引擎不解释语义仅原样透传
+   */
+  readonly repoId: string;
+  /**
+   * 仓库绝对路径，供宿主拉取执行器定位仓库
+   */
+  readonly repoPath: string;
+  /**
+   * 当前分支名，`null` 表示游离头指针或未诞生的仓库，规划层直接跳过
+   */
+  readonly branch: string | null;
+  /**
+   * 最近一次成功拉取时刻，毫秒时间戳，`null` 表示从未拉取视为立即到期
+   */
+  readonly lastFetchAt: number | null;
+  /**
+   * 最近一次活动时刻，毫秒时间戳，由宿主定义活动语义，`null` 视为休眠档
+   */
+  readonly lastActivityAt: number | null;
+  /**
+   * 是否存在未推送提交，存在时无条件归入活跃档
+   */
+  readonly hasUnpushed: boolean;
+  /**
+   * 既有失败退避状态，`null` 表示健康
+   */
+  readonly fetchState: FetchFailureState | null;
+};
+/**
+ * 三档 TTL 配置，单位毫秒
+ */
+type FetchTierTtlMs = {
+  /**
+   * 活跃档拉取间隔
+   */
+  readonly active: number;
+  /**
+   * 近期档拉取间隔
+   */
+  readonly recent: number;
+  /**
+   * 休眠档拉取间隔
+   */
+  readonly dormant: number;
+};
+/**
+ * 调度器选项
+ *
+ * 宿主可部分覆盖，未覆盖字段取引擎内置默认值
+ */
+type FetchSchedulerOptions = {
+  /**
+   * 三档拉取间隔
+   *
+   * @remarks
+   *   默认活跃档 15 分钟，近期档 1 小时，休眠档 12 小时
+   */
+  readonly tierTtlMs: FetchTierTtlMs;
+  /**
+   * 活跃档判定窗口，最近活动落在窗口内或存在未推送提交即归活跃档
+   *
+   * @default 21600000
+   */
+  readonly activeWindowMs: number;
+  /**
+   * 近期档判定窗口，最近活动落在窗口外且晚于休眠即归近期档
+   *
+   * @default 604800000
+   */
+  readonly recentWindowMs: number;
+  /**
+   * 每仓到期抖动比例，实际间隔在档位 TTL 上下浮动该比例，用于错峰
+   *
+   * @default 0.2
+   */
+  readonly jitterRatio: number;
+  /**
+   * 常驻轮询间隔
+   *
+   * @default 30000
+   */
+  readonly tickIntervalMs: number;
+  /**
+   * 单轮拉取并发上限
+   *
+   * @default 3
+   */
+  readonly concurrency: number;
+  /**
+   * 单仓拉取超时，超时按失败计入退避
+   *
+   * @default 120000
+   */
+  readonly fetchTimeoutMs: number;
+  /**
+   * 连续失败退避阶梯，第 n 次连续失败取下标 n 减一的位置，越界取末位
+   *
+   * @remarks
+   *   默认阶梯为 15 分钟，1 小时，4 小时
+   */
+  readonly backoffStepsMs: readonly number[];
+  /**
+   * 单轮最大派发数，到期的多余仓顺延到下一轮
+   *
+   * @default 64
+   */
+  readonly maxBatchSize: number;
+  /**
+   * 参与调度的分档集合，不在集合内的分档本轮不派发
+   *
+   * @remarks
+   *   默认三档全部参与
+   */
+  readonly tiers: readonly FetchTier[];
+};
+/**
+ * 调度器选项的用户覆盖形态
+ *
+ * 顶层字段与三档间隔嵌套字段均可部分覆盖，未覆盖字段取引擎内置默认值
+ */
+type FetchSchedulerOptionsOverrides = { readonly [K in Exclude<keyof FetchSchedulerOptions, 'tierTtlMs'>]?: FetchSchedulerOptions[K]; } & {
+  /**
+   * 三档拉取间隔的部分覆盖
+   */
+  readonly tierTtlMs?: Partial<FetchTierTtlMs>;
+};
+/**
+ * 单仓计划派发条目
+ */
+type PlannedFetch = {
+  /**
+   * 被选中派发的候选
+   */
+  readonly candidate: FetchCandidate;
+  /**
+   * 规划层判定的分档
+   */
+  readonly tier: FetchTier;
+};
+/**
+ * 规划统计计数
+ */
+type FetchPlanCounts = {
+  /**
+   * 因退避未到期被跳过的仓数
+   */
+  readonly skippedByBackoff: number;
+  /**
+   * 因无有效分支被跳过的仓数
+   */
+  readonly skippedNoBranch: number;
+  /**
+   * 分档 TTL 未到期未入选的仓数
+   */
+  readonly notDue: number;
+  /**
+   * 分档不在参与集合被跳过的仓数
+   */
+  readonly skippedOutOfTier: number;
+  /**
+   * 到期但因单轮上限顺延的仓数
+   */
+  readonly deferredByBatchCap: number;
+};
+/**
+ * 单轮规划结果
+ */
+type FetchPlan = {
+  /**
+   * 本轮派发目标列表，保持候选输入顺序
+   */
+  readonly targets: readonly PlannedFetch[];
+  /**
+   * 各类跳过与顺延的计数
+   */
+  readonly counts: FetchPlanCounts;
+};
+/**
+ * 调度器事件
+ */
+type FetchSchedulerEvent = {
+  /**
+   * 本轮开始派发
+   */
+  readonly kind: 'round-started';
+  /**
+   * 本轮派发目标数
+   */
+  readonly total: number;
+} | {
+  /**
+   * 单仓拉取成功
+   */
+  readonly kind: 'repo-fetched';
+  /**
+   * 宿主侧仓库标识
+   */
+  readonly repoId: string;
+  /**
+   * 本次拉取耗时
+   */
+  readonly durationMs: number;
+} | {
+  /**
+   * 单仓拉取失败并进入退避
+   */
+  readonly kind: 'repo-fetch-failed';
+  /**
+   * 宿主侧仓库标识
+   */
+  readonly repoId: string;
+  /**
+   * 失败错误描述
+   */
+  readonly error: string;
+  /**
+   * 失败后的连续失败次数
+   */
+  readonly consecutiveFailures: number;
+  /**
+   * 本次失败对应的退避截止时刻，毫秒时间戳
+   */
+  readonly backoffUntil: number | null;
+} | {
+  /**
+   * 本轮执行完毕
+   */
+  readonly kind: 'round-finished';
+  /**
+   * 成功拉取数
+   */
+  readonly done: number;
+  /**
+   * 失败数
+   */
+  readonly failed: number;
+  /**
+   * 规划层各类跳过与顺延的总数
+   */
+  readonly skipped: number;
+};
+/**
+ * 调度器依赖注入集合
+ */
+type FetchSchedulerDeps = {
+  /**
+   * 装载全部候选，每轮开始时调用一次
+   */
+  readonly loadCandidates: () => Promise<readonly FetchCandidate[]>;
+  /**
+   * 执行单仓拉取，抛错视为失败并计入退避
+   *
+   * @param candidate - 待拉取的候选
+   */
+  readonly fetchRepo: (candidate: FetchCandidate) => Promise<void>;
+  /**
+   * 拉取状态变更通知，成功传 `null` 清除退避，失败传新的退避状态
+   *
+   * @remarks
+   *   宿主据此持久化，引擎自身不落盘
+   * @param candidate - 状态变更的候选
+   * @param state - 新的退避状态或 `null`
+   */
+  readonly onFetchStateChange: (candidate: FetchCandidate, state: FetchFailureState | null) => Promise<void> | void;
+  /**
+   * 调度事件回调，可选
+   *
+   * @param event - 单条调度事件
+   */
+  readonly onEvent?: (event: FetchSchedulerEvent) => void;
+  /**
+   * 时钟注入，默认取 `Date.now`，测试注入伪时钟获得确定性
+   */
+  readonly now?: ClockSource;
+  /**
+   * 随机源注入，默认取 `Math.random`，测试注入固定值获得确定性抖动
+   */
+  readonly random?: RandomSource;
+  /**
+   * 选项部分覆盖，未覆盖字段取引擎内置默认值
+   */
+  readonly options?: FetchSchedulerOptionsOverrides;
+};
+/**
+ * 常驻调度器句柄
+ */
+type FetchScheduler = {
+  /**
+   * 启动常驻轮询，立即执行一轮后按 `tickIntervalMs` 周期执行，幂等
+   */
+  readonly start: () => void;
+  /**
+   * 停止常驻轮询，在途轮次自然收束不再派发新轮，幂等
+   */
+  readonly stop: () => void;
+  /**
+   * 手动执行一轮，与常驻轮询共享单飞闸门，在途时静默跳过
+   */
+  readonly tickNow: () => Promise<void>;
+  /**
+   * 常驻轮询是否在运行
+   */
+  readonly isRunning: () => boolean;
+};
+//#endregion
+//#region src/create-fetch-scheduler.factory.d.ts
+/**
+ * 引擎内置完整默认选项
+ */
+declare const DEFAULT_FETCH_SCHEDULER_OPTIONS: FetchSchedulerOptions;
+/**
+ * 部分选项到完整选项的解析
+ *
+ * 顶层字段浅合并，三档间隔嵌套合并，数组字段未提供时整体取默认
+ *
+ * @param partial - 宿主提供的部分选项，可为空
+ * @returns 合并默认值后的完整选项
+ */
+declare const resolveFetchSchedulerOptions: (partial?: FetchSchedulerOptionsOverrides) => FetchSchedulerOptions;
+/**
+ * 常驻 fetch 调度器创建
+ *
+ * 规划判定委托纯规划层，执行经并发池限流并带单仓超时，状态变更与事件经注入回调外抛
+ *
+ * @param deps - 宿主注入的依赖集合
+ * @returns 调度器句柄
+ */
+declare const createFetchScheduler: (deps: FetchSchedulerDeps) => FetchScheduler;
+//#endregion
+//#region src/planner.utils.d.ts
+/**
+ * 候选分档判定
+ *
+ * 存在未推送提交无条件归活跃档，随后按最近活动时刻对照窗口判定，无活动记录归休眠档
+ *
+ * @param candidate - 待判定的候选
+ * @param options - 完整调度选项
+ * @param now - 当前时刻，毫秒时间戳
+ * @returns 分档标识
+ */
+declare const resolveFetchTier: (candidate: FetchCandidate, options: FetchSchedulerOptions, now: number) => FetchTier;
+/**
+ * 带抖动的有效到期间隔计算
+ *
+ * 实际间隔等于档位 TTL 乘以一到加减抖动比例区间内的系数，随机源居中时系数恰为一
+ *
+ * @param tier - 分档标识
+ * @param options - 完整调度选项
+ * @param random - 随机源，取值区间零到一
+ * @returns 该仓本轮适用的有效到期间隔
+ */
+declare const effectiveTtlMs: (tier: FetchTier, options: FetchSchedulerOptions, random: RandomSource) => number;
+/**
+ * 候选到期判定
+ *
+ * 从未拉取视为立即到期，否则按距上次拉取时长对照带抖动的有效间隔判定
+ *
+ * @param candidate - 待判定的候选
+ * @param tier - 候选分档
+ * @param options - 完整调度选项
+ * @param now - 当前时刻，毫秒时间戳
+ * @param random - 随机源
+ * @returns 是否到期
+ */
+declare const isDue: (candidate: FetchCandidate, tier: FetchTier, options: FetchSchedulerOptions, now: number, random: RandomSource) => boolean;
+/**
+ * 单轮派发目标规划
+ *
+ * 逐候选完成分支过滤、退避过滤、分档判定、参与档过滤与到期筛选，到期目标按输入顺序截断到单轮上限
+ *
+ * @param candidates - 宿主装载的全部候选
+ * @param options - 完整调度选项
+ * @param now - 当前时刻，毫秒时间戳
+ * @param random - 随机源
+ * @returns 单轮规划结果
+ */
+declare const planFetchBatch: (candidates: readonly FetchCandidate[], options: FetchSchedulerOptions, now: number, random: RandomSource) => FetchPlan;
+//#endregion
+export { DEFAULT_FETCH_SCHEDULER_OPTIONS, type FetchCandidate, type FetchFailureState, type FetchPlan, type FetchPlanCounts, type FetchScheduler, type FetchSchedulerDeps, type FetchSchedulerEvent, type FetchSchedulerOptions, type FetchSchedulerOptionsOverrides, type FetchTier, type FetchTierTtlMs, type PlannedFetch, createFetchScheduler, effectiveTtlMs, isDue, planFetchBatch, resolveFetchSchedulerOptions, resolveFetchTier };

package/dist/index.js

@@ -0,0 +1 @@
+import{createSemaphoreScheduler as e}from"@longzai-intelligence-git/core";const t=(e,t,n)=>{if(e.hasUnpushed)return`active`;let r=e.lastActivityAt;if(r===null)return`dormant`;let i=n-r;return i<=t.activeWindowMs?`active`:i<=t.recentWindowMs?`recent`:`dormant`},n=(e,t,n)=>t.tierTtlMs[e]*(1+(n()*2-1)*t.jitterRatio),r=(e,t,r,i,a)=>{let o=e.lastFetchAt;return o===null||i-o>=n(t,r,a)},i=(e,n,i,a)=>{let o=[],s=0,c=0,l=0,u=0,d=new Set(n.tiers);for(let f of e){if(f.branch===null){c+=1;continue}let e=f.fetchState?.backoffUntil??null;if(e!==null&&e>i){s+=1;continue}let p=t(f,n,i);if(!d.has(p)){u+=1;continue}if(!r(f,p,n,i,a)){l+=1;continue}o.push({candidate:f,tier:p})}let f=o.slice(0,n.maxBatchSize),p=o.length-f.length;return{targets:f,counts:{skippedByBackoff:s,skippedNoBranch:c,notDue:l,skippedOutOfTier:u,deferredByBatchCap:p}}},a={active:9e5,recent:36e5,dormant:432e5},o={tierTtlMs:a,activeWindowMs:216e5,recentWindowMs:6048e5,jitterRatio:.2,tickIntervalMs:3e4,concurrency:3,fetchTimeoutMs:12e4,backoffStepsMs:[9e5,36e5,144e5],maxBatchSize:64,tiers:[`active`,`recent`,`dormant`]},s=e=>({...o,...e,tierTtlMs:{...a,...e?.tierTtlMs},backoffStepsMs:e?.backoffStepsMs??o.backoffStepsMs,tiers:e?.tiers??o.tiers}),c=(e,t,n,r)=>{let i=e===null?1:e.consecutiveFailures+1;return r.length===0?{consecutiveFailures:i,backoffUntil:null,lastError:t}:{consecutiveFailures:i,backoffUntil:n+(r[Math.min(i-1,r.length-1)]??0),lastError:t}},l=t=>{let n=s(t.options),r=e(),a=null,o=!1,l=t.now??Date.now,u=t.random??Math.random,d=e=>{try{t.onEvent?.(e)}catch{return}},f=async()=>{let e=await t.loadCandidates(),a=i(e,n,l(),u);a.targets.length>0&&d({kind:`round-started`,total:a.targets.length});let o=a.targets.map(e=>({input:e,run:e=>t.fetchRepo(e.candidate)})),s=await r.schedule(o,{concurrency:n.concurrency,timeoutMs:n.fetchTimeoutMs,retries:0}),f=0,p=0;for(let e=0;e<s.length;e+=1){let r=a.targets[e];if(r===void 0)continue;let i=s[e];if(i===void 0)continue;let o=l();if(i.ok){f+=1,await t.onFetchStateChange(r.candidate,null),d({kind:`repo-fetched`,repoId:r.candidate.repoId,durationMs:i.durationMs});continue}p+=1;let u=i.error?.message??`未知错误`,m=c(r.candidate.fetchState,u,o,n.backoffStepsMs);await t.onFetchStateChange(r.candidate,m),d({kind:`repo-fetch-failed`,repoId:r.candidate.repoId,error:u,consecutiveFailures:m.consecutiveFailures,backoffUntil:m.backoffUntil})}let m=a.counts.skippedByBackoff+a.counts.skippedNoBranch+a.counts.notDue+a.counts.skippedOutOfTier+a.counts.deferredByBatchCap;d({kind:`round-finished`,done:f,failed:p,skipped:m})};return{start:()=>{a===null&&(f(),a=setInterval(()=>{f()},n.tickIntervalMs))},stop:()=>{a!==null&&(clearInterval(a),a=null)},tickNow:async()=>{if(!o){o=!0;try{await f()}finally{o=!1}}},isRunning:()=>a!==null}};export{o as DEFAULT_FETCH_SCHEDULER_OPTIONS,l as createFetchScheduler,n as effectiveTtlMs,r as isDue,i as planFetchBatch,s as resolveFetchSchedulerOptions,t as resolveFetchTier};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@longzai-intelligence-git/fetch-scheduler",
+  "version": "0.1.7",
+  "description": "Longzai Intelligence Git 多仓拉取调度引擎",
+  "keywords": [
+    "fetch",
+    "git",
+    "longzai-intelligence",
+    "scheduler",
+    "tiering"
+  ],
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "lzi-builder",
+    "build:prod": "NODE_ENV=production bun run build",
+    "prepublishOnly": "bun run build:prod",
+    "typecheck": "bun run typecheck:app && bun run typecheck:node && bun run typecheck:test",
+    "typecheck:app": "lzi-tsgo typecheck tsconfig/app.json",
+    "typecheck:node": "lzi-tsgo typecheck tsconfig/node.json",
+    "typecheck:test": "lzi-tsgo typecheck tsconfig/test.json",
+    "lint": "oxlint && oxfmt --check",
+    "lint:fix": "oxlint --fix && oxfmt",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "test:coverage": "bun test --coverage",
+    "clean": "lzi-dev-cli clean"
+  },
+  "dependencies": {
+    "@longzai-intelligence-git/core": "0.1.7"
+  }
+}