publish

package
v1.3.7 Latest Latest
Warning

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

Go to latest
Published: Jul 6, 2026 License: MIT Imports: 26 Imported by: 0

Documentation

Index

Constants

View Source
const CatalogFileName = "catalog.json"

Variables

View Source
var (
	// ErrUnauthorized means the caller did not present a recognized publish token.
	ErrUnauthorized = errors.New("unauthorized")
	// ErrForbidden means the token is known but not allowed for the requested package/version.
	ErrForbidden = errors.New("forbidden")
)
View Source
var (
	ErrVersionAlreadyExists        = errors.New("version already exists")
	ErrPackageQuotaExceeded        = errors.New("package storage quota exceeded")
	ErrPackageVersionQuotaExceeded = errors.New("package version quota exceeded")
)

Functions

func ConstantTimeTokenHashEqual

func ConstantTimeTokenHashEqual(a, b string) bool

ConstantTimeTokenHashEqual compares canonical token hash strings without leaking which byte differed.

func DBFileName

func DBFileName(packageName string) (string, error)

DBFileName returns the canonical SQLite export file name for packageName.

func HashPublishToken

func HashPublishToken(rawToken string) string

HashPublishToken returns the canonical hash form stored for a raw publish token.

func NormalizeTokenHash

func NormalizeTokenHash(tokenHash string) (string, error)

NormalizeTokenHash validates and normalizes a stored token hash.

func PackageVersionDBPath

func PackageVersionDBPath(packageName, version string) (string, error)

PackageVersionDBPath returns the relative canonical DB path for a package version, e.g. pinocchio/v1.2.3/pinocchio.db.

func PackageVersionDir

func PackageVersionDir(packageName, version string) (string, error)

PackageVersionDir returns the relative directory for a package/version pair.

func ValidatePackageName

func ValidatePackageName(name string) error

ValidatePackageName checks whether name is safe to use as a docs package identity and as one path segment below the package publication root.

func ValidatePackageVersion

func ValidatePackageVersion(packageName, version string) error

ValidatePackageVersion validates the package/version pair used by publish APIs and filesystem materialization.

func ValidateVersion

func ValidateVersion(version string) error

ValidateVersion checks whether version is safe to use as a package version identity and as one path segment below the package publication root.

Types

type DirectoryPackageStore

type DirectoryPackageStore struct {
	Root                  string
	Now                   func() time.Time
	AllowOverwrite        bool
	MaxPackageBytes       int64
	MaxVersionsPerPackage int
}

func NewDirectoryPackageStore

func NewDirectoryPackageStore(root string) *DirectoryPackageStore

func (*DirectoryPackageStore) List

func (*DirectoryPackageStore) Publish

func (s *DirectoryPackageStore) Publish(ctx context.Context, packageName, version, dbPath string, result *SQLiteValidationResult, identity *PublisherIdentity) (*PublishedPackage, error)

type FilePublisherCatalogSource

type FilePublisherCatalogSource struct {
	Path string
}

FilePublisherCatalogSource loads Phase 1 publisher token records from a JSON file. It mirrors the Vault record shape and is useful for local smoke tests and operator-synced Vault exports.

func (FilePublisherCatalogSource) LoadPublisherTokenRecords

func (s FilePublisherCatalogSource) LoadPublisherTokenRecords(ctx context.Context) ([]PublisherTokenRecord, error)

type JWTPublisherAuth added in v1.3.1

type JWTPublisherAuth struct {
	Issuer   string
	ClientID string
	// contains filtered or unexported fields
}

JWTPublisherAuth authorizes package publishes with OIDC-compliant JWTs.

This auth mode is intended for Vault Identity/OIDC publish tokens. Vault signs a short-lived token with audience "docs-registry" and a package claim. The registry validates the token through OIDC discovery/JWKS and then checks that the package claim matches the requested package.

func NewJWTPublisherAuth added in v1.3.1

func NewJWTPublisherAuth(ctx context.Context, issuer, clientID string) (*JWTPublisherAuth, error)

NewJWTPublisherAuth constructs a JWT publisher auth implementation using OIDC discovery from issuer. clientID is the expected JWT audience.

func (*JWTPublisherAuth) AuthorizePublish added in v1.3.1

func (a *JWTPublisherAuth) AuthorizePublish(ctx context.Context, rawToken string, req PublishRequest) (*PublisherIdentity, error)

AuthorizePublish validates rawToken as an OIDC JWT and authorizes it for req.

type PackageCatalog

type PackageCatalog struct {
	UpdatedAt time.Time          `json:"updatedAt"`
	Packages  []PublishedPackage `json:"packages"`
}

type PackageQuotaExceededError added in v1.3.5

type PackageQuotaExceededError struct {
	PackageName string
	MaxBytes    int64
	Projected   int64
}

func (*PackageQuotaExceededError) Error added in v1.3.5

func (e *PackageQuotaExceededError) Error() string

func (*PackageQuotaExceededError) Unwrap added in v1.3.5

func (e *PackageQuotaExceededError) Unwrap() error

type PackageStore

type PackageStore interface {
	Publish(ctx context.Context, packageName, version, dbPath string, result *SQLiteValidationResult, identity *PublisherIdentity) (*PublishedPackage, error)
	List(ctx context.Context) ([]PublishedPackage, error)
}

PackageStore persists a validated package docs DB and can list published packages.

type PackageVersionQuotaExceededError added in v1.3.5

type PackageVersionQuotaExceededError struct {
	PackageName string
	MaxVersions int
	Projected   int
}

func (*PackageVersionQuotaExceededError) Error added in v1.3.5

func (*PackageVersionQuotaExceededError) Unwrap added in v1.3.5

type PublishRequest

type PublishRequest struct {
	PackageName string
	Version     string
}

PublishRequest is the authorization request for publishing one package version.

type PublishedPackage

type PublishedPackage struct {
	PackageName  string    `json:"packageName"`
	Version      string    `json:"version"`
	SectionCount int       `json:"sectionCount"`
	SlugCount    int       `json:"slugCount"`
	Path         string    `json:"path,omitempty"`
	SHA256       string    `json:"sha256,omitempty"`
	PublishedBy  string    `json:"publishedBy,omitempty"`
	PublishedAt  time.Time `json:"publishedAt,omitempty"`
}

PublishedPackage is a lightweight registry catalog entry.

type PublisherAuth

type PublisherAuth interface {
	AuthorizePublish(ctx context.Context, rawToken string, req PublishRequest) (*PublisherIdentity, error)
}

PublisherAuth authorizes package/version publishing requests.

type PublisherCatalogSource

type PublisherCatalogSource interface {
	LoadPublisherTokenRecords(ctx context.Context) ([]PublisherTokenRecord, error)
}

PublisherCatalogSource loads package publisher records from a backing source such as a fixture file, Vault KV path, or later registry database.

type PublisherIdentity

type PublisherIdentity struct {
	Subject        string `json:"subject"`
	PackageName    string `json:"packageName"`
	Method         string `json:"method"`
	Repository     string `json:"repository,omitempty"`
	RepositoryID   string `json:"repositoryId,omitempty"`
	WorkflowRef    string `json:"workflowRef,omitempty"`
	JobWorkflowRef string `json:"jobWorkflowRef,omitempty"`
	RunID          string `json:"runId,omitempty"`
}

PublisherIdentity describes the authenticated publisher after authorization.

type PublisherTokenRecord

type PublisherTokenRecord struct {
	PackageName string    `json:"package" yaml:"package"`
	Subject     string    `json:"subject,omitempty" yaml:"subject,omitempty"`
	TokenHash   string    `json:"tokenHash" yaml:"token_hash"`
	CreatedAt   time.Time `json:"createdAt,omitempty" yaml:"created_at,omitempty"`
	RotatedAt   time.Time `json:"rotatedAt,omitempty" yaml:"rotated_at,omitempty"`
	RevokedAt   time.Time `json:"revokedAt,omitempty" yaml:"revoked_at,omitempty"`
	Notes       string    `json:"notes,omitempty" yaml:"notes,omitempty"`
}

PublisherTokenRecord mirrors the Phase 1 Vault/static catalog record shape. The raw publish token is never represented here; only its hash is stored.

func (PublisherTokenRecord) ToStaticPublisherToken

func (r PublisherTokenRecord) ToStaticPublisherToken() (StaticPublisherToken, bool)

ToStaticPublisherToken converts a non-revoked catalog record into a static auth token entry.

type RegistryHandler

type RegistryHandler struct {
	Auth                    PublisherAuth
	Store                   PackageStore
	MaxUploadBytes          int64
	TempDir                 string
	MaxConcurrentUploads    int
	RateLimitRequestsPerMin int
	RateLimitBurst          int
	Metrics                 *RegistryMetrics
	// contains filtered or unexported fields
}

RegistryHandler serves the Phase 1 docs publishing registry API.

func NewRegistryHandler

func NewRegistryHandler(auth PublisherAuth, store PackageStore) *RegistryHandler

func (*RegistryHandler) Handler

func (h *RegistryHandler) Handler() http.Handler

type RegistryMetrics added in v1.3.5

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

RegistryMetrics stores low-cardinality docs-registry counters.

The registry currently runs as a single replica, so in-process counters are sufficient for immediate operational visibility. If the registry scales out, these metrics should be scraped from every pod and aggregated by Prometheus.

func NewRegistryMetrics added in v1.3.5

func NewRegistryMetrics() *RegistryMetrics

func (*RegistryMetrics) PrometheusText added in v1.3.5

func (m *RegistryMetrics) PrometheusText() string

func (*RegistryMetrics) RecordPublish added in v1.3.5

func (m *RegistryMetrics) RecordPublish(event publishAuditEvent)

func (*RegistryMetrics) RecordRequest added in v1.3.5

func (m *RegistryMetrics) RecordRequest(routeClass, method string, status int)

func (*RegistryMetrics) ServeHTTP added in v1.3.5

func (m *RegistryMetrics) ServeHTTP(w http.ResponseWriter, _ *http.Request)

type ReloadablePublisherCatalog

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

ReloadablePublisherCatalog keeps the active PublisherAuth implementation in memory and can replace it after reloading token records from a source.

func NewReloadablePublisherCatalog

func NewReloadablePublisherCatalog(source PublisherCatalogSource) *ReloadablePublisherCatalog

func (*ReloadablePublisherCatalog) AuthorizePublish

func (c *ReloadablePublisherCatalog) AuthorizePublish(ctx context.Context, rawToken string, req PublishRequest) (*PublisherIdentity, error)

AuthorizePublish delegates to the currently loaded auth implementation.

func (*ReloadablePublisherCatalog) Reload

Reload loads token records from the source and swaps in a new StaticTokenAuth only after all records validate.

type SQLiteValidationOptions

type SQLiteValidationOptions struct {
	PackageName string
	Version     string
}

SQLiteValidationOptions controls validation of a Glazed help SQLite export.

type SQLiteValidationResult

type SQLiteValidationResult struct {
	Path         string   `json:"path"`
	PackageName  string   `json:"packageName,omitempty"`
	Version      string   `json:"version,omitempty"`
	SectionCount int      `json:"sectionCount"`
	SlugCount    int      `json:"slugCount"`
	Warnings     []string `json:"warnings,omitempty"`
}

SQLiteValidationResult summarizes a validated help database.

func ValidateSQLiteHelpDB

func ValidateSQLiteHelpDB(ctx context.Context, path string, opts SQLiteValidationOptions) (*SQLiteValidationResult, error)

ValidateSQLiteHelpDB opens path read-only and verifies that it looks like a Glazed help SQLite export that is safe to publish for the requested package and version.

type SimpleRateLimiter added in v1.3.5

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

func NewSimpleRateLimiter added in v1.3.5

func NewSimpleRateLimiter(requestsPerMinute, burst int) *SimpleRateLimiter

func (*SimpleRateLimiter) Allow added in v1.3.5

func (l *SimpleRateLimiter) Allow(key string) bool

type StaticPublisherCatalogSource

type StaticPublisherCatalogSource struct {
	Records []PublisherTokenRecord
}

StaticPublisherCatalogSource is an in-memory source useful for tests and local fixtures before direct Vault loading is implemented.

func (StaticPublisherCatalogSource) LoadPublisherTokenRecords

func (s StaticPublisherCatalogSource) LoadPublisherTokenRecords(ctx context.Context) ([]PublisherTokenRecord, error)

type StaticPublisherToken

type StaticPublisherToken struct {
	Subject     string
	PackageName string
	TokenHash   string
}

StaticPublisherToken binds one token hash to exactly one package.

func StaticTokensFromRecords

func StaticTokensFromRecords(records []PublisherTokenRecord) ([]StaticPublisherToken, error)

StaticTokensFromRecords validates catalog records and returns static auth tokens for all non-revoked records.

type StaticTokenAuth

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

StaticTokenAuth authorizes publishes against an in-memory package token list.

func NewStaticTokenAuth

func NewStaticTokenAuth(tokens []StaticPublisherToken) (*StaticTokenAuth, error)

NewStaticTokenAuth validates and constructs static package-token auth.

func (*StaticTokenAuth) AuthorizePublish

func (a *StaticTokenAuth) AuthorizePublish(ctx context.Context, rawToken string, req PublishRequest) (*PublisherIdentity, error)

AuthorizePublish authorizes rawToken for req. It intentionally compares the presented token hash with stored hashes using constant-time comparison.

type VersionAlreadyExistsError added in v1.3.5

type VersionAlreadyExistsError struct {
	PackageName string
	Version     string
}

func (*VersionAlreadyExistsError) Error added in v1.3.5

func (e *VersionAlreadyExistsError) Error() string

func (*VersionAlreadyExistsError) Unwrap added in v1.3.5

func (e *VersionAlreadyExistsError) Unwrap() error

Jump to

Keyboard shortcuts

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