util

package
v0.0.0-...-f374552 Latest Latest
Warning

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

Go to latest
Published: Nov 22, 2026 License: MulanPSL-2.0 Imports: 26 Imported by: 0

Documentation

Index

Constants

View Source
const (
	// DeprecatedRegistryRelPath 是集市弃用注册表在仓库根目录下的相对路径。
	DeprecatedRegistryRelPath = "deprecated.json"
)
View Source
const ThemeJsAllowlistRelPath = "config/themes-theme-js-allowlist.txt"

ThemeJsAllowlistRelPath 为仓库根目录下「允许包含 theme.js」的主题列表相对路径。

View Source
const UserAgent = "bazaar/1.0.0 https://github.com/siyuan-note/bazaar"

Variables

View Source
var (
	QINIU_BUCKET = os.Getenv("QINIU_BUCKET")
	QINIU_AK     = os.Getenv("QINIU_AK")
	QINIU_SK     = os.Getenv("QINIU_SK")
)
View Source
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")
)
View Source
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

func CheckRepoLicenseFile(ctx context.Context, client *github.Client, owner, repo string) error

CheckRepoLicenseFile 确认仓库默认分支根目录存在 `LICENSE` 或 `LICENSE.txt`(大小写不敏感),且文件非空。 缺失时返回 LocalizedError(cause 为 ErrRepoNoLicense);空文件为 ErrRepoEmptyLicense;API 失败时同样返回 LocalizedError。

func CheckRepoPublic

func CheckRepoPublic(ctx context.Context, client *github.Client, owner, repo string) error

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

func GitHubRepoURL(ownerRepo string) string

GitHubRepoURL 由 owner/repo 拼出仓库主页地址

func IsGitHubNotFound

func IsGitHubNotFound(err error) bool

IsGitHubNotFound 判断 err 是否为 GitHub REST API 的 404 Not Found。 可穿透 LocalizedError / fmt %w 等包装链。

func IsGitHubRateLimit

func IsGitHubRateLimit(err error) bool

IsGitHubRateLimit 判断 err 是否为 GitHub REST API 主限流或次级(滥用)限流。 可穿透 LocalizedError / fmt %w 等包装链。

func IsGitHubServerError

func IsGitHubServerError(err error) bool

IsGitHubServerError 判断 err 是否为 GitHub REST API 的 5xx 服务端错误。 常见于瞬时故障;可穿透 LocalizedError / fmt %w 等包装链。

func LoadOccupiedNames

func LoadOccupiedNames(bazaarHead string) (map[string]struct{}, error)

LoadOccupiedNames 从 bazaarHead 下的 stage/*.json 收集已占用 package.name(键为小写)。

func LoadReposByPackageType

func LoadReposByPackageType(repoRoot string) (map[rules.PackageType][]string, error)

LoadReposByPackageType 读取仓库根目录下的五个集市包列表。

func MarshalSortedIndentedJSON

func MarshalSortedIndentedJSON(v any) ([]byte, error)

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

func NewGitHubClient(token string, timeout time.Duration) (*github.Client, error)

NewGitHubClient 创建带 Token、超时与 User-Agent 的 GitHub API 客户端。

func NormalizeAssetDigest

func NormalizeAssetDigest(digest string) string

NormalizeAssetDigest 将 GitHub asset digest(`sha256:<hex>` 或裸 hex)规范为 64 位小写 hex。 无法解析时返回空字符串。

func OwnerRepoFromStageURL

func OwnerRepoFromStageURL(stageURL string) (ownerRepo string, ok bool)

OwnerRepoFromStageURL 从 stage 条目的 URL(格式 owner/repo@hash)中解析 owner/repo。 hash 为 package.zip 内容 SHA-256 hex 的前 7 位(见 PackageHashFromSHA256)。

func PackageHashFromDigest

func PackageHashFromDigest(digest string) string

PackageHashFromDigest 由 GitHub asset digest 生成集市包 hash。

func PackageHashFromSHA256

func PackageHashFromSHA256(sha256Hex string) string

PackageHashFromSHA256 由 64 位 SHA-256 hex 生成集市包 hash(前 packageHashLen 位)。

func ParseReposFromBytes

func ParseReposFromBytes(fileLabel string, data []byte) (repos []string, err error)

ParseReposFromBytes 从 TXT 内容解析包列表,规则与 ParseReposFromTxt 相同(跳过空行)。 fileLabel 用于错误文案(通常为文件名,如 plugins.txt)。

func ParseReposFromBytesStrict

func ParseReposFromBytesStrict(fileLabel string, data []byte) (repos []string, err error)

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

func ParseReposFromTxt(filePath string) (repos []string, err error)

ParseReposFromTxt 从 TXT 文件解析包列表:按行分割、跳过空行,校验每行为合法 owner/repo,返回 []string。 不做 TrimSpace,行首尾或 owner/repo 内含空格均视为解析错误。兼容多种换行符(\n、\r\n、\r)。 空行与重复 owner/repo 是否允许不在本函数把关:Stage / 弃用校验 / 巡检用宽松语义 (跳过空行、重复项保留首次出现并记警告),PR Check 用 ParseReposFromTxtStrict。

func ParseReposFromTxtStrict

func ParseReposFromTxtStrict(filePath string) (repos []string, err error)

ParseReposFromTxtStrict 与 ParseReposFromTxt 相同,但额外要求空行只能出现在文件末尾且最多一行, 且同一个 owner/repo 只能出现一次。 仅供 PR Check 校验本 PR 提交的列表文件:Stage 读的是 main 上的既有内容,不应因一处多余空行整轮失败。

func SHA256Hex

func SHA256Hex(data []byte) string

SHA256Hex 计算数据的 SHA-256 并返回小写 hex。

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

func UnzipPackageZipData(data []byte) (unzipDir string, cleanup func(), err error)

UnzipPackageZipData 将已下载的 package.zip 字节解压到临时目录。 cleanup 删除临时工作目录,调用方应 defer cleanup()。

func UploadOSS

func UploadOSS(ctx context.Context, key string, data []byte) (err error)

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

func ReadStageFile(filePath string) (*StageFile, error)

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);读取/解析失败时返回错误。

Jump to

Keyboard shortcuts

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