Documentation
¶
Index ¶
- Constants
- Variables
- func ApplyDeprecatedRegistry(packageType rules.PackageType, repos []StageRepo, registry *DeprecatedRegistry, ...) []string
- func ChangedDeprecatedTypes(before, after *DeprecatedRegistry) []rules.PackageType
- func CheckRepoLicenseFile(ctx context.Context, client *github.Client, owner, repo string) error
- func CheckRepoPublic(ctx context.Context, client *github.Client, owner, repo string) error
- func DownloadAndUnzipPackageZip(ctx context.Context, client *github.Client, owner, repo string, assetID int64) (unzipDir string, zipData []byte, cleanup func(), err error)
- func DownloadPackageZip(ctx context.Context, client *github.Client, owner, repo string, assetID int64) ([]byte, error)
- func FormatRateHeaderObservation(label string, obs *RateHeaderObserver) string
- func GitHubRepoURL(ownerRepo string) string
- func IsGitHubNotFound(err error) bool
- func IsGitHubRateLimit(err error) bool
- func IsGitHubServerError(err error) bool
- func LoadOccupiedNames(bazaarHead string) (map[string]struct{}, error)
- func LoadReposByPackageType(repoRoot string) (map[rules.PackageType][]string, error)
- func MarshalSortedIndentedJSON(v any) ([]byte, error)
- func NewDeprecatedTargets(reposByType map[rules.PackageType][]StageRepo) map[string]DeprecatedTarget
- func NewGitHubClient(token string, timeout time.Duration) (*github.Client, error)
- func NormalizeAssetDigest(digest string) string
- func OwnerRepoFromStageURL(stageURL string) (ownerRepo string, ok bool)
- func PackageHashFromDigest(digest string) string
- func PackageHashFromSHA256(sha256Hex string) string
- func ParseReposFromBytes(fileLabel string, data []byte) (repos []string, err error)
- func ParseReposFromBytesStrict(fileLabel string, data []byte) (repos []string, err error)
- func ParseReposFromBytesWithMode(fileLabel string, data []byte, strict bool) (repos []string, err error)
- func ParseReposFromTxt(filePath string) (repos []string, err error)
- func ParseReposFromTxtStrict(filePath string) (repos []string, err error)
- func SHA256Hex(data []byte) string
- func SeedRateHeaderBaseline(ctx context.Context, client *github.Client, owner, repo string) (github.Rate, error)
- func UnzipPackageZipData(data []byte) (unzipDir string, cleanup func(), err error)
- func UploadOSS(ctx context.Context, key string, data []byte) (err error)
- func UploadOSSWithContentType(ctx context.Context, key string, data []byte, contentType string) (err error)
- func ValidateDeprecatedRegistry(registry *DeprecatedRegistry, reposByType map[rules.PackageType][]string) []rules.Issue
- func ValidateDeprecatedRegistryTypes(registry *DeprecatedRegistry, reposByType map[rules.PackageType][]string, ...) []rules.Issue
- type DeprecatedEntry
- type DeprecatedRegistry
- type DeprecatedTarget
- type LatestRelease
- func FetchLatestRelease(ctx context.Context, client *github.Client, owner, repo string) (LatestRelease, error)
- func FetchLatestReleaseZip(ctx context.Context, client *github.Client, owner, repo string) (LatestRelease, error)
- func ProbeLatestRelease(ctx context.Context, client *github.Client, owner, repo string) (LatestRelease, error)
- type RateHeaderObserver
- type RateHeaderSnapshot
- type StageFile
- type StageIndexFile
- type StageIndexRepo
- type StageRepo
Constants ¶
const (
// DeprecatedRegistryRelPath 是集市弃用注册表在仓库根目录下的相对路径。
DeprecatedRegistryRelPath = "deprecated.json"
)
const ThemeJsAllowlistRelPath = "config/themes-theme-js-allowlist.txt"
ThemeJsAllowlistRelPath 为仓库根目录下「允许包含 theme.js」的主题列表相对路径。
const UserAgent = "bazaar/1.0.0 https://github.com/siyuan-note/bazaar"
Variables ¶
var ( QINIU_BUCKET = os.Getenv("QINIU_BUCKET") QINIU_AK = os.Getenv("QINIU_AK") QINIU_SK = os.Getenv("QINIU_SK") )
var ( // ErrNoLatestRelease 仓库没有 Latest Release,或 GitHub API 读取失败。 ErrNoLatestRelease = errors.New("no latest release") // ErrNoPackageZip Latest Release 中缺少名为 `package.zip` 的资源。 ErrNoPackageZip = errors.New("package.zip not found in latest release") // ErrReleaseTag 无法将 Release tag 解析为有效 commit。 ErrReleaseTag = errors.New("release tag could not be resolved") )
var ( // ErrRepoNotPublic 仓库不存在、无法访问,或未设为公开。 ErrRepoNotPublic = errors.New("repository is not public") // ErrRepoNoLicense 仓库根目录缺少 LICENSE / LICENSE.txt。 ErrRepoNoLicense = errors.New("repository has no LICENSE or LICENSE.txt") // ErrRepoEmptyLicense 仓库根目录的 LICENSE / LICENSE.txt 存在但无正文(空文件)。 ErrRepoEmptyLicense = errors.New("repository LICENSE file is empty") )
Functions ¶
func ApplyDeprecatedRegistry ¶
func ApplyDeprecatedRegistry(packageType rules.PackageType, repos []StageRepo, registry *DeprecatedRegistry, targets map[string]DeprecatedTarget) []string
ApplyDeprecatedRegistry 先清除全部 Stage 生成字段,再按注册表覆盖当前类型条目。 targets 提供跨类型替代包解析(见 NewDeprecatedTargets)。 Alternatives 只收同类型目标:旧客户端按源包类型打开替代包,跨类型目标会查不到; Choices 收全部目标(含同类型),是客户端跨类型跳转的依据。 返回的警告表示 Stage 数据不足或注册表语义异常;调用方应记录并继续生成安全的索引。
func ChangedDeprecatedTypes ¶
func ChangedDeprecatedTypes(before, after *DeprecatedRegistry) []rules.PackageType
ChangedDeprecatedTypes 返回两个注册表之间内容发生变化的包类型。
func CheckRepoLicenseFile ¶
CheckRepoLicenseFile 确认仓库默认分支根目录存在 `LICENSE` 或 `LICENSE.txt`(大小写不敏感),且文件非空。 缺失时返回 LocalizedError(cause 为 ErrRepoNoLicense);空文件为 ErrRepoEmptyLicense;API 失败时同样返回 LocalizedError。
func CheckRepoPublic ¶
CheckRepoPublic 确认仓库可通过 GitHub API 访问且为公开仓库。 私有、不存在或无权访问时返回 LocalizedError(cause 为 ErrRepoNotPublic)。
func DownloadAndUnzipPackageZip ¶
func DownloadAndUnzipPackageZip(ctx context.Context, client *github.Client, owner, repo string, assetID int64) (unzipDir string, zipData []byte, cleanup func(), err error)
DownloadAndUnzipPackageZip 通过 GitHub Release Asset API 下载 `package.zip` 并解压到临时目录。 zipData 供 Stage 上传 OSS;cleanup 删除临时工作目录,调用方应 defer cleanup()。
func DownloadPackageZip ¶
func DownloadPackageZip(ctx context.Context, client *github.Client, owner, repo string, assetID int64) ([]byte, error)
DownloadPackageZip 通过 GitHub Release Asset API 下载 `package.zip` 原始字节。
func FormatRateHeaderObservation ¶
func FormatRateHeaderObservation(label string, obs *RateHeaderObserver) string
FormatRateHeaderObservation 格式化当次 core 请求次数与开始/结束剩余配额日志行。
func GitHubRepoURL ¶
GitHubRepoURL 由 owner/repo 拼出仓库主页地址
func IsGitHubNotFound ¶
IsGitHubNotFound 判断 err 是否为 GitHub REST API 的 404 Not Found。 可穿透 LocalizedError / fmt %w 等包装链。
func IsGitHubRateLimit ¶
IsGitHubRateLimit 判断 err 是否为 GitHub REST API 主限流或次级(滥用)限流。 可穿透 LocalizedError / fmt %w 等包装链。
func IsGitHubServerError ¶
IsGitHubServerError 判断 err 是否为 GitHub REST API 的 5xx 服务端错误。 常见于瞬时故障;可穿透 LocalizedError / fmt %w 等包装链。
func LoadOccupiedNames ¶
LoadOccupiedNames 从 bazaarHead 下的 stage/*.json 收集已占用 package.name(键为小写)。
func LoadReposByPackageType ¶
func LoadReposByPackageType(repoRoot string) (map[rules.PackageType][]string, error)
LoadReposByPackageType 读取仓库根目录下的五个集市包列表。
func MarshalSortedIndentedJSON ¶
MarshalSortedIndentedJSON 序列化为键序稳定、带缩进的 JSON。 v 可为 struct,或原始 JSON 字节([]byte);struct 会先经 json.Marshal / Unmarshal 转为 JSON 树(map[string]any), 再按字典序输出键。先输出紧凑 JSON,再用 json.Indent 缩进,避免 json.MarshalIndent 对嵌套 any 的缩进错乱。 SetEscapeHTML(false) 避免将 & 等字符转为 \uXXXX。
这是 stage/*.json 唯一的写出格式:stage 与回填工具共用,避免两处各写一份导致格式漂移。
func NewDeprecatedTargets ¶
func NewDeprecatedTargets(reposByType map[rules.PackageType][]StageRepo) map[string]DeprecatedTarget
NewDeprecatedTargets 从各类 Stage 条目建立 owner/repo → 替代包 的解析表。 必须传入全部类型的 Stage 数据:替代包可以跨类型,只看本类型会漏掉跨类型目标。 同一 owner/repo 只应属于一个类型(列表唯一性由 rules.Check 保证),重复时保留先出现的类型。
func NewGitHubClient ¶
NewGitHubClient 创建带 Token、超时与 User-Agent 的 GitHub API 客户端。
func NormalizeAssetDigest ¶
NormalizeAssetDigest 将 GitHub asset digest(`sha256:<hex>` 或裸 hex)规范为 64 位小写 hex。 无法解析时返回空字符串。
func OwnerRepoFromStageURL ¶
OwnerRepoFromStageURL 从 stage 条目的 URL(格式 owner/repo@hash)中解析 owner/repo。 hash 为 package.zip 内容 SHA-256 hex 的前 7 位(见 PackageHashFromSHA256)。
func PackageHashFromDigest ¶
PackageHashFromDigest 由 GitHub asset digest 生成集市包 hash。
func PackageHashFromSHA256 ¶
PackageHashFromSHA256 由 64 位 SHA-256 hex 生成集市包 hash(前 packageHashLen 位)。
func ParseReposFromBytes ¶
ParseReposFromBytes 从 TXT 内容解析包列表,规则与 ParseReposFromTxt 相同(跳过空行)。 fileLabel 用于错误文案(通常为文件名,如 plugins.txt)。
func ParseReposFromBytesStrict ¶
ParseReposFromBytesStrict 从 TXT 内容解析包列表,额外要求空行只能出现在文件末尾且最多一行, 且同一个 owner/repo 只能出现一次。
func ParseReposFromBytesWithMode ¶
func ParseReposFromBytesWithMode(fileLabel string, data []byte, strict bool) (repos []string, err error)
ParseReposFromBytesWithMode 按 strict 决定是否把中间空行与重复 owner/repo 视为错误。 strict 只用于 PR Check:它要提示作者改掉多余空行与重复行,而 Stage 读的是 main 上的既有内容。 宽松模式下重复项保留首次出现,避免 stage 索引出现两个指向同一仓库的条目。
func ParseReposFromTxt ¶
ParseReposFromTxt 从 TXT 文件解析包列表:按行分割、跳过空行,校验每行为合法 owner/repo,返回 []string。 不做 TrimSpace,行首尾或 owner/repo 内含空格均视为解析错误。兼容多种换行符(\n、\r\n、\r)。 空行与重复 owner/repo 是否允许不在本函数把关:Stage / 弃用校验 / 巡检用宽松语义 (跳过空行、重复项保留首次出现并记警告),PR Check 用 ParseReposFromTxtStrict。
func ParseReposFromTxtStrict ¶
ParseReposFromTxtStrict 与 ParseReposFromTxt 相同,但额外要求空行只能出现在文件末尾且最多一行, 且同一个 owner/repo 只能出现一次。 仅供 PR Check 校验本 PR 提交的列表文件:Stage 读的是 main 上的既有内容,不应因一处多余空行整轮失败。
func SeedRateHeaderBaseline ¶
func SeedRateHeaderBaseline(ctx context.Context, client *github.Client, owner, repo string) (github.Rate, error)
SeedRateHeaderBaseline 串行打一次计入 core 的 API(GET /repos/{owner}/{repo}),用真实响应头锚定观测起点,并返回该响应的 Rate。 使用本仓 repos.get:PAT 与 Actions GITHUB_TOKEN(Metadata)均可访问;勿用 GET /user(installation token 会 403)。 不要用 GET /rate_limit:其 remaining 可能与后续业务响应头不一致。
func UnzipPackageZipData ¶
UnzipPackageZipData 将已下载的 package.zip 字节解压到临时目录。 cleanup 删除临时工作目录,调用方应 defer cleanup()。
func UploadOSSWithContentType ¶
func UploadOSSWithContentType(ctx context.Context, key string, data []byte, contentType string) (err error)
UploadOSSWithContentType 上传对象并显式设置 MIME 类型。
func ValidateDeprecatedRegistry ¶
func ValidateDeprecatedRegistry(registry *DeprecatedRegistry, reposByType map[rules.PackageType][]string) []rules.Issue
ValidateDeprecatedRegistry 校验源包、替代包与多语言原因;源包须在同类列表中,替代包须恰属于一个类型列表。
func ValidateDeprecatedRegistryTypes ¶
func ValidateDeprecatedRegistryTypes(registry *DeprecatedRegistry, reposByType map[rules.PackageType][]string, packageTypes []rules.PackageType) []rules.Issue
ValidateDeprecatedRegistryTypes 只校验指定包类型,供 PR Check 避免被其他类型的既有防御性警告阻断。
Types ¶
type DeprecatedEntry ¶
type DeprecatedEntry struct {
Reason rules.LocaleStrings `json:"reason,omitempty"`
Alternatives []string `json:"alternatives,omitempty"`
}
DeprecatedEntry 描述一个仍上架、但不再建议新用户选用的集市包。
type DeprecatedRegistry ¶
type DeprecatedRegistry struct {
Plugins map[string]DeprecatedEntry `json:"plugins"`
Themes map[string]DeprecatedEntry `json:"themes"`
Icons map[string]DeprecatedEntry `json:"icons"`
Templates map[string]DeprecatedEntry `json:"templates"`
Widgets map[string]DeprecatedEntry `json:"widgets"`
}
DeprecatedRegistry 按集市包类型保存弃用元数据。
func ParseDeprecatedRegistry ¶
func ParseDeprecatedRegistry(fileLabel string, data []byte) (*DeprecatedRegistry, error)
ParseDeprecatedRegistry 严格解析弃用注册表,拒绝重复键、未知字段、缺失类型与显式 null。
func ReadDeprecatedRegistry ¶
func ReadDeprecatedRegistry(filePath string) (*DeprecatedRegistry, error)
ReadDeprecatedRegistry 读取并严格解析弃用注册表。
func (*DeprecatedRegistry) Entries ¶
func (r *DeprecatedRegistry) Entries(packageType rules.PackageType) map[string]DeprecatedEntry
Entries 返回指定包类型的弃用条目。
type DeprecatedTarget ¶
type DeprecatedTarget struct {
PackageType rules.PackageType
Choice rules.PackageChoice
}
DeprecatedTarget 为一个 owner/repo 解析出的替代包:来源类型与下发给客户端的选项。
type LatestRelease ¶
type LatestRelease struct {
ID int64 // GitHub Release ID(指纹用)
Tag string
URL string
Published string // RFC3339
PackageZipAssetID int64
PackageZipDigest string // package.zip 的 digest,形如 sha256:<hex>
PackageZipUpdatedAt string // package.zip 的 updated_at,RFC3339;指纹用
CommitSHA string
}
LatestRelease 仓库 Latest Release 的纯数据摘要。
func FetchLatestRelease ¶
func FetchLatestRelease(ctx context.Context, client *github.Client, owner, repo string) (LatestRelease, error)
FetchLatestRelease 获取 Latest Release,并校验 `package.zip` 与 tag → commit。
返回的 error 用 sentinel(ErrNoLatestRelease / ErrNoPackageZip / ErrReleaseTag)标识失败阶段。
若在 GetLatestRelease 之后失败(缺 `package.zip` 或 tag 无效),仍返回已取到的 Tag、URL 等字段: PR Check 的评论模板 check-result.md.tpl 在报错时也会渲染 Release 链接,便于作者点开对应 Release 补传 zip 或修 tag。
func FetchLatestReleaseZip ¶
func FetchLatestReleaseZip(ctx context.Context, client *github.Client, owner, repo string) (LatestRelease, error)
FetchLatestReleaseZip 获取 Latest Release,并校验存在 `package.zip`,不解析 tag→commit。 PackageZipDigest 若 GitHub 已提供则填入(可能为空,Stage 可再下载计算 SHA-256)。
返回的 error 用 sentinel(ErrNoLatestRelease / ErrNoPackageZip)标识失败阶段。 若在 GetLatestRelease 之后因缺少 `package.zip` 失败,仍返回已取到的 Tag、URL 等字段。
func ProbeLatestRelease ¶
func ProbeLatestRelease(ctx context.Context, client *github.Client, owner, repo string) (LatestRelease, error)
ProbeLatestRelease 仅拉取 Latest Release 与 package.zip 指纹字段,不解析 tag→commit。 供定时复检在 prepare 阶段做廉价变更探测;无 package.zip 时仍返回已取到的 Release 字段(Zip ID 为 0)。
type RateHeaderObserver ¶
type RateHeaderObserver struct {
// contains filtered or unexported fields
}
RateHeaderObserver 通过 HTTP Transport 采集 GitHub REST 响应头中的 rate limit。
func NewGitHubClientWithRateObserver ¶
func NewGitHubClientWithRateObserver(token string, timeout time.Duration) (*github.Client, *RateHeaderObserver, error)
NewGitHubClientWithRateObserver 同 NewGitHubClient,并挂载响应头观测 Transport。
func (*RateHeaderObserver) Snapshot ¶
func (o *RateHeaderObserver) Snapshot() RateHeaderSnapshot
Snapshot 返回当前观测快照。
type RateHeaderSnapshot ¶
type RateHeaderSnapshot struct {
Samples int // 计入 core 配额的响应次数(本客户端实际 core 请求数)
Limit int
StartRemaining int // 第一次计入 samples 的请求之前的剩余(由该响应 Remaining+1 还原)
FirstRemaining int // 第一次计入 samples 的响应头 Remaining(该请求已扣减后)
LastRemaining int // 最后一次观测到的 Remaining(结束时剩余配额)
MinRemaining int
FirstUsed int
LastUsed int
MaxUsed int
HasData bool
}
RateHeaderSnapshot 汇总本客户端实际 API 响应头中的 X-RateLimit-*(仅 core)。 官方建议优先用响应头而非单独轮询 GET /rate_limit;本观测器完全忽略 /rate_limit。
type StageFile ¶
type StageFile struct {
Repos []StageRepo `json:"repos"`
}
StageFile 对应 stage/*.json 顶层结构。
func ReadStageFile ¶
ReadStageFile 读取并解析 stage JSON 文件。文件不存在时返回空 StageFile(不报错)。
func (StageFile) ForPublicIndex ¶
func (f StageFile) ForPublicIndex() StageIndexFile
ForPublicIndex 转为供客户端使用的集市索引,去掉 stage 流程内部字段, 并剔除与 default 值相同的冗余多语言键(对 locale map 做拷贝,不修改原 stage 条目)。
type StageIndexFile ¶
type StageIndexFile struct {
Repos []StageIndexRepo `json:"repos"`
}
StageIndexFile 供 OSS 集市索引发布的 stage JSON,不含 stage 流程内部字段。
type StageIndexRepo ¶
type StageIndexRepo struct {
URL string `json:"url"`
RepoRef string `json:"repoRef,omitempty"`
Created string `json:"created"`
Updated string `json:"updated"`
Stars int `json:"stars"`
OpenIssues int `json:"openIssues"`
Size int64 `json:"size"`
InstallSize int64 `json:"installSize"`
Package rules.Package `json:"package"`
}
StageIndexRepo 对应发布后集市索引 repos 数组的单项。
type StageRepo ¶
type StageRepo struct {
URL string `json:"url"`
RepoRef string `json:"repoRef,omitempty"`
Created string `json:"created"` // 首次进入集市的时间(RFC3339);写入后不再改变,与 updated(最近一次发布)不同
Updated string `json:"updated"`
Stars int `json:"stars"`
OpenIssues int `json:"openIssues"`
Size int64 `json:"size"`
InstallSize int64 `json:"installSize"`
PackageZipAssetID int64 `json:"packageZipAssetId,omitempty"`
PackageZipSHA256 string `json:"packageZipSha256,omitempty"` // 完整 SHA-256 hex;仅 stage 内部,不进公开索引
Package rules.Package `json:"package"`
}
StageRepo 对应 stage/*.json 中 repos 数组的单项。
func FindStageRepo ¶
func FindStageRepo(bazaarHead string, packageType rules.PackageType, ownerRepo string) (*StageRepo, error)
FindStageRepo 从 bazaarHead/stage/<type>.json 中按 owner/repo 查找条目。 文件不存在或未找到时返回 (nil, nil);读取/解析失败时返回错误。