layout

package
v0.90.0 Latest Latest
Warning

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

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

Documentation

Overview

Package layout defines media object keys, dependency-free so the media gateway can classify paths without importing the media runtime: 

{namespace}/{kind}/{id}/manifest.json         gzip JSON; never served
                       /private/sha256-{hex}-{uuid}  uploads, derived files, editor views
                       /private/sha256-{hex}  a pre-v0.68 item's blob, kept by the upgrade
                       /download/sha256-{hex}-{uuid} originals, full-resolution files and archives: only a download token opens them
                       /public/{name}         app-declared names, e.g. cover-460.webp
                       /temp/{name}           in-flight writes and staged uploads (u-{uuid}); never served
{namespace}/{kind}/{id}/{version}/...         a content version's item, laid out alike
{namespace}/{kind}/_default/public/{name}     a public preset's default image

A content kind's media lives in its versions' folders, within its {id} folder, which holds no item of its own. The URL of an object is its key under /v1/ on the site's media host.

Index

Constants

View Source 
const (
	AreaManifest = "manifest"
	AreaPrivate  = "private"
	AreaDownload = "download"
	AreaPublic   = "public"
	AreaTemp     = "temp"
)

Folder areas.

View Source 
const (
	// ManifestName is the manifest's key within the folder.
	ManifestName = "manifest.json"
	// ErasureFenceName is reserved gateway state, never a public rendition.
	ErasureFenceName = "_contentkit_erased"
	// DefaultID is the item id under which a kind's default public images live.
	DefaultID = "_default"
	// SHA256Prefix starts every blob name.
	SHA256Prefix = "sha256-"
	// StagedPrefix starts a staged upload's name in temp/.
	StagedPrefix = "u-"
	// URLPrefix is the path every media URL starts with.
	URLPrefix = "/v1/"
)
View Source 
const MaxDownloadName = 200

MaxDownloadName bounds a download name in bytes.

Variables

This section is empty.

Functions

func Attachment added in v0.62.0 

func Attachment(name string) string

Attachment is the Content-Disposition for a download name: an ASCII fallback plus the RFC 5987 UTF-8 name.

func BlobDigest added in v0.68.0 

func BlobDigest(ref string) ([]byte, bool)

BlobDigest returns the content digest of a blob reference.

func BlobName added in v0.68.0 

func BlobName(sum []byte, allocation string) string

BlobName names one physical allocation of SHA-256 bytes. A later write, even of identical bytes, must receive a different allocation UUID.

func BlobRef added in v0.90.0 

func BlobRef(area, name string) string

BlobRef is the reference of an allocation named name in area.

func CheckBuckets added in v0.79.0 

func CheckBuckets(in map[string]string) (map[string]string, error)

CheckBuckets validates a namespace -> bucket map. It returns a copy.

func CheckHosts added in v0.62.0 

func CheckHosts(in map[string][]string) (map[string][]string, error)

CheckHosts validates a host map: lower-case names without a port, each with valid namespaces. It returns a copy.

func CompileDefaults added in v0.62.0 

func CompileDefaults(defs []Default) (map[string]map[string]string, error)

CompileDefaults validates and copies the exact fallback selection.

func Disposition added in v0.62.0 

func Disposition(name, contentType string) string

Disposition is the Content-Disposition of a download requested as name (the URL's unsigned dl) for an object of contentType: always an attachment. The name is used only when it is plain (no path separator, control character or bidirectional format character, at most MaxDownloadName bytes) and ends in an extension of the object's type, so a link cannot rename a file into another type, or make it read as one.

func DownloadExt added in v0.90.0 

func DownloadExt(contentType string) string

DownloadExt is the extension a download name of an object of contentType ends in: its first, or "" when the type has none.

func DownloadName added in v0.90.0 

func DownloadName(name, ext string) string

DownloadName is name as a download name Disposition keeps when ext is its object's: without the characters it refuses and leading dots, cut to fit MaxDownloadName with ext, then ext. "" when nothing of name is left.

func FormatBuckets added in v0.79.0 

func FormatBuckets(m map[string]string) string

FormatBuckets is ParseBuckets' inverse, with namespaces sorted.

func FormatDefaults added in v0.62.0 

func FormatDefaults(defs []Default) string

FormatDefaults is ParseDefaults' inverse, with entries sorted by namespace and kind.

func FormatHosts added in v0.62.0 

func FormatHosts(m map[string][]string) string

FormatHosts is ParseHosts' inverse, with hosts sorted.

func ParseBuckets added in v0.79.0 

func ParseBuckets(s string) (map[string]string, error)

ParseBuckets parses "doujins=prod-doujins; hentai0=prod-hentai0; accounts=prod-doujins": each namespace's bucket. A shared namespace lives in its owning app's bucket.

func ParseHosts added in v0.62.0 

func ParseHosts(s string) (map[string][]string, error)

ParseHosts parses "media.doujins.ai=doujins,accounts; media.hanime.media=hentai0,accounts".

func ParseSHA256Name 

func ParseSHA256Name(name string) ([]byte, bool)

ParseSHA256Name returns the digest of a "sha256-{hex}" name.

func Prefix added in v0.62.0 

func Prefix(namespace, kind, id, version string) string

Prefix is an item's folder: "{namespace}/{kind}/{id}/", and a version's "{namespace}/{kind}/{id}/{version}/".

func SHA256Name added in v0.62.0 

func SHA256Name(sum []byte) string

SHA256Name names a digest, not a physical allocation: "sha256-{hex}".

func SplitBlobRef added in v0.90.0 

func SplitBlobRef(ref string) (area, name string, ok bool)

SplitBlobRef is a blob reference's area and allocation name.

func ValidBlobName 

func ValidBlobName(name string) bool

ValidBlobName accepts a private allocation: "sha256-{hex}-{uuid}", or a legacy "sha256-{hex}" the upgrade adopted. New writes always get a UUID.

func ValidBlobRef added in v0.90.0 

func ValidBlobRef(ref string) bool

ValidBlobRef accepts a blob reference.

func ValidHashName added in v0.48.0 

func ValidHashName(name string) bool

ValidHashName accepts "sha256-{64 lowercase hex}".

func ValidPublicName added in v0.68.0 

func ValidPublicName(name string) bool

ValidPublicName also accepts the generation suffix on a logical public filename. Only object names gain that allowance; folder segments keep their existing bounds. Default images use content-addressed names.

func ValidSegment 

func ValidSegment(s string) bool

ValidSegment keeps keys stable ASCII: [A-Za-z0-9._-]{1,128}, no leading dot.

func ValidStagedName added in v0.40.0 

func ValidStagedName(name string) bool

ValidStagedName accepts "u-{uuid}", a canonical lowercase UUID.

func ValidVersion added in v0.82.0 

func ValidVersion(s string) bool

ValidVersion accepts a version folder's segment: a valid segment that is no area, manifest or reserved "_" name.

Types

type Default added in v0.62.0 

type Default struct {
	Namespace, Kind string
	Files           map[string]string // logical name -> sha256-{digest}.webp
}

Default maps logical public names to immutable rendered default objects. The gateway uses this deployment-owned selection only when an item is missing.

func ParseDefaults added in v0.62.0 

func ParseDefaults(s string) ([]Default, error)

ParseDefaults parses "doujins/gallery: cover-460.webp=sha256-{digest}.webp".

type Key 

type Key struct {
	Namespace, Kind, ID string
	Scope               Scope
	Version             string // "" outside a version's folder
	Area                string
	Name                string // the name within the area; "" for the manifest
}

Key is a parsed object key.

func Parse 

func Parse(key string) (Key, bool)

Parse classifies an object key; ok is false for anything outside the layout.

func ParseFolder added in v0.82.0 

func ParseFolder(prefix string) (Key, bool)

ParseFolder parses an item folder, "{namespace}/{kind}/{id}/" or a version's "{namespace}/{kind}/{id}/{version}/".

func (Key) Folder added in v0.82.0 

func (k Key) Folder() string

Folder is the key's item folder.

type Scope added in v0.90.0 

type Scope struct {
	TenantID string `json:"tenant_id"`
	AppID    string `json:"app_id,omitempty"`
}

Scope is the trusted owner of a media root. An empty AppID identifies tenant account media; a nonempty AppID identifies one app's catalog media. The zero value retains the legacy single-segment layout.

func ScopeFromPartition added in v0.90.0 

func ScopeFromPartition(p string) (Scope, bool)

func (Scope) IsZero added in v0.90.0 

func (s Scope) IsZero() bool

func (Scope) Partition added in v0.90.0 

func (s Scope) Partition() string

Partition is an internal database/job key. It is never an object path or a caller-selected namespace. Including both IDs prevents reused app IDs in different tenants from sharing quotas, caches or work.

func (Scope) Prefix added in v0.90.0 

func (s Scope) Prefix(kind, id, version string) string

func (Scope) Root added in v0.90.0 

func (s Scope) Root() string

func (Scope) Valid added in v0.90.0 

func (s Scope) Valid() bool

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.