Help us shape the future of Go! Take the 2026 Go Developer Survey

ociartifacts

package
v1.9.1 Latest Latest
Warning

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

Go to latest
Published: Nov 1, 2026 License: MIT Imports: 38 Imported by: 0

README

OCI Artifacts and Container Registry

Parity grade: B · SDK github.com/oracle/oci-go-sdk/v65@v65.126.2 · last audited 2026-10-30 (4f3e4c057)

Coverage

Metric Value
PARITY entries audited 37 (32 ok, 5 partial)
Feature families 10 (2 ok, 8 partial)
Known gaps 7
Deferred items 0
Resource leaks unknown
Known gaps
  • Auth tokens are not validated: OCI Identity discards them after CreateAuthToken, so any non-empty token with a / login is accepted, and the user part is not checked against Identity users. IAM policies, repository policies, resource principals and instance principals are not applied; only API-key signatures are verified on the control plane.
  • Registry hostnames are not modelled: one host:port serves every region key and the namespace is the first path segment, as OCIR paths are (.ocir.io//). The generic artifact content API is served on the control-plane listener instead of generic.artifacts..oci.oraclecloud.com. No TLS (docker treats localhost registries as insecure).
  • Unverified, chosen by the emulator: 409 Conflict for duplicate repository names, identical signatures and immutable generic overwrites; 409 TAG_INVALID for immutable tag overwrites; isRepositoryCreatedOnFirstPush defaulting to true; billableSizeInGBs as whole GB rounded up; DeleteRepository cascading to artifacts; the 256 MiB artifact cap; one-hour registry token lifetime; the unversioned image displayName form.
  • Repositories and images have no DELETING window: deletes are immediate (images soft-delete to DELETED until restored; repositories vanish). OCI's deletion retention, repository quotas and per-image limits are not modelled, and blobs of deleted images are not garbage collected.
  • createdBy on images and versions is the registry login user name rather than a user OCID; signatures and repositories created through the API use the signing user OCID.
  • pullCount counts GET manifest requests only, including ones the registry then rejects; blob pulls and HEAD requests do not count. Image scanning, vulnerability reports and replication are not provided.
  • opc-retry-token idempotency and compartmentIdInSubtree outside OCI Identity are not applied; systemTags are always empty.

More

Documentation

Overview

Package ociartifacts emulates OCI Artifacts and Container Registry: the 20160918 control plane (container repositories, images, signatures, container configuration, generic repositories and artifacts), the generic artifact content API and an OCIR-style Docker Registry v2 endpoint with token authentication, all on one dedicated listener. See PARITY.md.

Index

Constants

View Source
const (
	// Region is the fixed region baked into emulated OCIDs.
	Region = "us-ashburn-1"
	// DefaultNamespace is the tenancy namespace served unless overridden.
	DefaultNamespace = "gopherstack"
	// DefaultTenancy is the root compartment used for repositories created by a first push.
	DefaultTenancy = "ocid1.tenancy.oc1..aaaaaaaagopherstackemulatedtenancy000000000000000000000000"
)
View Source
const DefaultPort = 8166

DefaultPort is the dedicated listener's default TCP port.

Variables

View Source
var ErrNilAppContext = errors.New("ociartifacts: nil app context")

ErrNilAppContext is returned when Init is called with a nil AppContext.

View Source
var ErrSnapshotNull = errors.New("ociartifacts: null entry in snapshot")

ErrSnapshotNull is returned when a snapshot contains a null entry.

Functions

This section is empty.

Types

type APIError

type APIError struct {
	Code    string
	Message string
	Status  int
}

APIError is an OCI error response: HTTP status plus the `code` and `message` body fields.

func (*APIError) Error

func (e *APIError) Error() string

type ConfigProvider

type ConfigProvider interface {
	GetOCIArtifactsSettings() Settings
}

ConfigProvider extracts OCI Artifacts configuration from the AppContext Config.

type DataDirConfig

type DataDirConfig interface {
	GetRegistryDataDir() string
}

DataDirConfig locates the directory registry blobs are kept in; empty keeps them in memory.

type GenericArtifact

type GenericArtifact struct {
	TimeCreated time.Time `json:"timeCreated"`
	Tags        Tags      `json:"tags"`
	ID          string    `json:"id"`
	RepoID      string    `json:"repoId"`
	Path        string    `json:"path"`
	Version     string    `json:"version"`
	Sha256      string    `json:"sha256"`
	Etag        string    `json:"etag"`
	Content     []byte    `json:"content"`
	Seq         int64     `json:"seq"`
}

GenericArtifact is one uploaded generic artifact version.

type GenericContent

type GenericContent struct {
	Etag    string
	Sha256  string
	Content []byte
}

GenericContent is an artifact body with its etag.

type GenericRepo

type GenericRepo struct {
	TimeCreated   time.Time `json:"timeCreated"`
	Tags          Tags      `json:"tags"`
	ID            string    `json:"id"`
	Name          string    `json:"name"`
	Description   string    `json:"description"`
	CompartmentID string    `json:"compartmentId"`
	Etag          string    `json:"etag"`
	Seq           int64     `json:"seq"`
	IsImmutable   bool      `json:"isImmutable"`
}

GenericRepo is a generic artifacts repository.

type Handler

type Handler struct {
	Backend *InMemoryBackend

	Port        int
	EnforceAuth bool
	// contains filtered or unexported fields
}

Handler serves OCI Artifacts and Container Registry.

func NewHandler

func NewHandler(backend *InMemoryBackend) *Handler

NewHandler creates a Handler; callers override Port and EnforceAuth from Settings.

func (*Handler) ExtractOperation

func (h *Handler) ExtractOperation(c *echo.Context) string

ExtractOperation returns the operation name for metrics.

func (*Handler) ExtractResource

func (h *Handler) ExtractResource(c *echo.Context) string

ExtractResource returns the addressed resource id for metrics.

func (*Handler) GetSupportedOperations

func (h *Handler) GetSupportedOperations() []string

GetSupportedOperations lists the supported operations.

func (*Handler) Handler

func (h *Handler) Handler() echo.HandlerFunc

Handler returns the Echo handler for all OCIArtifacts requests.

func (*Handler) MatchPriority

func (h *Handler) MatchPriority() int

MatchPriority is irrelevant because RouteMatcher never matches.

func (*Handler) Name

func (h *Handler) Name() string

Name returns the service name.

func (*Handler) Reset

func (h *Handler) Reset()

Reset clears all in-memory state.

func (*Handler) Restore

func (h *Handler) Restore(ctx context.Context, data []byte) error

Restore implements persistence.Persistable by delegating to the backend.

func (*Handler) RouteMatcher

func (h *Handler) RouteMatcher() service.Matcher

RouteMatcher never matches: OCIArtifacts runs on its own listener.

func (*Handler) Shutdown

func (h *Handler) Shutdown(ctx context.Context)

Shutdown stops the listener and releases the embedded registry.

func (*Handler) Snapshot

func (h *Handler) Snapshot(ctx context.Context) []byte

Snapshot implements persistence.Persistable by delegating to the backend.

func (*Handler) StartWorker

func (h *Handler) StartWorker(ctx context.Context) error

StartWorker binds the dedicated listener synchronously so a port conflict is returned to the caller.

func (*Handler) Trusted

func (h *Handler) Trusted() echo.HandlerFunc

Trusted returns a handler that skips request-signature verification, for the in-process dashboard proxy.

type Image

type Image struct {
	TimeCreated    time.Time  `json:"timeCreated"`
	TimeLastPulled *time.Time `json:"timeLastPulled,omitempty"`
	Tags           Tags       `json:"tags"`
	ID             string     `json:"id"`
	RepoID         string     `json:"repoId"`
	Digest         string     `json:"digest"`
	CreatedBy      string     `json:"createdBy"`
	State          string     `json:"state"`
	LastVersion    string     `json:"lastVersion,omitempty"`
	Etag           string     `json:"etag"`
	Versions       []Version  `json:"versions"`
	Layers         []Layer    `json:"layers"`
	LayersSize     int64      `json:"layersSize"`
	PullCount      int64      `json:"pullCount"`
	Seq            int64      `json:"seq"`
	ManifestSize   int        `json:"manifestSize"`
}

Image is a manifest pushed to a container repository.

type InMemoryBackend

type InMemoryBackend struct {
	Auth *ociauth.Registry
	// contains filtered or unexported fields
}

InMemoryBackend holds every resource under one lock; image blobs live in an embedded registry.

func NewInMemoryBackend

func NewInMemoryBackend() *InMemoryBackend

NewInMemoryBackend creates an empty backend that keeps image blobs in memory.

func (*InMemoryBackend) ChangeContainerRepositoryCompartment

func (b *InMemoryBackend) ChangeContainerRepositoryCompartment(id, ifMatch string, in changeCompartmentIn) error

ChangeContainerRepositoryCompartment moves a repository.

func (*InMemoryBackend) ChangeRepositoryCompartment

func (b *InMemoryBackend) ChangeRepositoryCompartment(id, ifMatch string, in changeCompartmentIn) error

ChangeRepositoryCompartment moves a generic repository.

func (*InMemoryBackend) Close

func (b *InMemoryBackend) Close()

Close releases the embedded registry.

func (*InMemoryBackend) Compartments

func (b *InMemoryBackend) Compartments() []string

Compartments lists the tenancy root and every compartment that holds a repository.

func (*InMemoryBackend) CreateContainerImageSignature

func (b *InMemoryBackend) CreateContainerImageSignature(
	in createSignatureIn, createdBy string,
) (signatureWire, string, error)

CreateContainerImageSignature stores a signature for an image.

func (*InMemoryBackend) CreateContainerRepository

func (b *InMemoryBackend) CreateContainerRepository(in createRepoIn, createdBy string) (repoWire, string, error)

CreateContainerRepository creates a repository; createdBy is the signing user's OCID.

func (*InMemoryBackend) CreateRepository

func (b *InMemoryBackend) CreateRepository(in createGenericRepoIn) (genericRepoWire, string, error)

CreateRepository creates a generic artifacts repository.

func (*InMemoryBackend) DeleteContainerImage

func (b *InMemoryBackend) DeleteContainerImage(id, ifMatch string) error

DeleteContainerImage marks an image DELETED; it stops resolving on pull until restored.

func (*InMemoryBackend) DeleteContainerImageSignature

func (b *InMemoryBackend) DeleteContainerImageSignature(id, ifMatch string) error

DeleteContainerImageSignature deletes a signature.

func (*InMemoryBackend) DeleteContainerRepository

func (b *InMemoryBackend) DeleteContainerRepository(id, ifMatch string) error

DeleteContainerRepository deletes a repository with its images and signatures, and their stored blobs.

func (*InMemoryBackend) DeleteGenericArtifact

func (b *InMemoryBackend) DeleteGenericArtifact(id, ifMatch string) error

DeleteGenericArtifact deletes an artifact by id.

func (*InMemoryBackend) DeleteGenericArtifactByPath

func (b *InMemoryBackend) DeleteGenericArtifactByPath(repoID, path, version, ifMatch string) error

DeleteGenericArtifactByPath deletes an artifact by repository, path and version.

func (*InMemoryBackend) DeleteRepository

func (b *InMemoryBackend) DeleteRepository(id, ifMatch string) error

DeleteRepository deletes a generic repository together with its artifacts.

func (*InMemoryBackend) EnsureRepo

func (b *InMemoryBackend) EnsureRepo(display, user string) *APIError

EnsureRepo creates the repository on first push when the container configuration allows it.

func (*InMemoryBackend) GetContainerConfiguration

func (b *InMemoryBackend) GetContainerConfiguration(compartment string) (configWire, string, error)

GetContainerConfiguration returns the tenancy's container configuration.

func (*InMemoryBackend) GetContainerImage

func (b *InMemoryBackend) GetContainerImage(id string) (imageWire, string, error)

GetContainerImage returns an image (including DELETED ones) and its etag.

func (*InMemoryBackend) GetContainerImageSignature

func (b *InMemoryBackend) GetContainerImageSignature(id string) (signatureWire, string, error)

GetContainerImageSignature returns a signature and its etag.

func (*InMemoryBackend) GetContainerRepository

func (b *InMemoryBackend) GetContainerRepository(id string) (repoWire, string, error)

GetContainerRepository returns a repository and its etag.

func (*InMemoryBackend) GetGenericArtifact

func (b *InMemoryBackend) GetGenericArtifact(id string) (genericArtifactWire, string, error)

GetGenericArtifact returns an artifact by id.

func (*InMemoryBackend) GetGenericArtifactByPath

func (b *InMemoryBackend) GetGenericArtifactByPath(repoID, path, version string) (genericArtifactWire, string, error)

GetGenericArtifactByPath returns an artifact by repository, path and version.

func (*InMemoryBackend) GetGenericArtifactContent

func (b *InMemoryBackend) GetGenericArtifactContent(id string) (GenericContent, error)

GetGenericArtifactContent returns an artifact's bytes by id.

func (*InMemoryBackend) GetGenericArtifactContentByPath

func (b *InMemoryBackend) GetGenericArtifactContentByPath(repoID, path, version string) (GenericContent, error)

GetGenericArtifactContentByPath returns an artifact's bytes by repository, path and version.

func (*InMemoryBackend) GetRepository

func (b *InMemoryBackend) GetRepository(id string) (genericRepoWire, string, error)

GetRepository returns a generic repository and its etag.

func (*InMemoryBackend) IssueToken

func (b *InMemoryBackend) IssueToken(user string, anon bool, scopes []Scope) (string, []Scope, int)

IssueToken returns a signed registry token and its lifetime in seconds. Scopes are granted as requested; an anonymous token is limited to pull.

func (*InMemoryBackend) ListContainerImageSignatures

func (b *InMemoryBackend) ListContainerImageSignatures(
	f signatureFilter, o ListOpts,
) (signatureCollectionWire, string, error)

ListContainerImageSignatures lists the signatures of a compartment.

func (*InMemoryBackend) ListContainerImages

func (b *InMemoryBackend) ListContainerImages(f imageFilter, o ListOpts) (imageCollectionWire, string, error)

ListContainerImages lists the images of a compartment.

func (*InMemoryBackend) ListContainerRepositories

func (b *InMemoryBackend) ListContainerRepositories(f repoFilter, o ListOpts) (repoCollectionWire, string, error)

ListContainerRepositories lists repositories of a compartment.

func (*InMemoryBackend) ListGenericArtifacts

func (b *InMemoryBackend) ListGenericArtifacts(
	f genericArtifactFilter, o ListOpts,
) (genericArtifactCollectionWire, string, error)

ListGenericArtifacts lists the artifacts of a repository.

func (*InMemoryBackend) ListRepositories

func (b *InMemoryBackend) ListRepositories(f genericRepoFilter, o ListOpts) (genericRepoCollectionWire, string, error)

ListRepositories lists the generic repositories of a compartment.

func (*InMemoryBackend) LookupContainerImageByURI

func (b *InMemoryBackend) LookupContainerImageByURI(uri string) (imageWire, string, error)

LookupContainerImageByURI finds an image by `namespace/repo:version` or `namespace/repo@digest`.

func (*InMemoryBackend) Namespace

func (b *InMemoryBackend) Namespace() string

Namespace returns the tenancy namespace.

func (*InMemoryBackend) ParseToken

func (b *InMemoryBackend) ParseToken(token string) (tokenClaims, bool)

ParseToken verifies a registry token's signature and expiry.

func (*InMemoryBackend) PermitManifest

func (b *InMemoryBackend) PermitManifest(display, ref, op, digest string, pull bool) int

PermitManifest decides whether a manifest read, write or delete may proceed. digest is the digest of the body being written, when known.

func (*InMemoryBackend) PutGenericArtifactContentByPath

func (b *InMemoryBackend) PutGenericArtifactContentByPath(
	repoID, path, version, ifMatch string, content []byte,
) (genericArtifactWire, string, error)

PutGenericArtifactContentByPath uploads an artifact, replacing the version in a mutable repository.

func (*InMemoryBackend) RecordDelete

func (b *InMemoryBackend) RecordDelete(display, ref string)

RecordDelete forgets a manifest deleted through the registry API, or just the tag when ref is one.

func (*InMemoryBackend) RecordPush

func (b *InMemoryBackend) RecordPush(display, ref, digest, user string, body []byte)

RecordPush notes a stored manifest as an image of the repository, tagging it when ref is a tag.

func (*InMemoryBackend) RemoveContainerVersion

func (b *InMemoryBackend) RemoveContainerVersion(id, ifMatch string, in removeVersionIn) (imageWire, string, error)

RemoveContainerVersion removes one version from an image.

func (*InMemoryBackend) RepoAccess

func (b *InMemoryBackend) RepoAccess(display string) (repoAccess, bool)

RepoAccess looks up the repository addressed by a display name.

func (*InMemoryBackend) Reset

func (b *InMemoryBackend) Reset()

Reset clears all state and removes stored blobs.

func (*InMemoryBackend) Restore

func (b *InMemoryBackend) Restore(ctx context.Context, data []byte) error

Restore loads backend state from a snapshot.

func (*InMemoryBackend) RestoreContainerImage

func (b *InMemoryBackend) RestoreContainerImage(id, ifMatch string, in restoreImageIn) (imageWire, string, error)

RestoreContainerImage brings a DELETED image back, optionally under a new version.

func (*InMemoryBackend) SetClock

func (b *InMemoryBackend) SetClock(now func() time.Time)

SetClock injects the time source for timestamps and token expiry.

func (*InMemoryBackend) SetCompartmentChecker

func (b *InMemoryBackend) SetCompartmentChecker(fn func(string) bool)

SetCompartmentChecker validates compartmentId arguments against another service (OCI Identity).

func (*InMemoryBackend) SetCompartmentTree

func (b *InMemoryBackend) SetCompartmentTree(fn func(id, ancestor string) bool)

SetCompartmentTree tells the backend whether a compartment is nested below another (OCI Identity).

func (*InMemoryBackend) SetContext

func (b *InMemoryBackend) SetContext(ctx context.Context)

SetContext bounds the lifetime of the embedded registry.

func (*InMemoryBackend) SetDataDir

func (b *InMemoryBackend) SetDataDir(dir string)

SetDataDir keeps image blobs and manifests under dir; empty keeps them in memory.

func (*InMemoryBackend) SetNamespace

func (b *InMemoryBackend) SetNamespace(ns string)

SetNamespace overrides the tenancy namespace used in registry paths.

func (*InMemoryBackend) SetTenancy

func (b *InMemoryBackend) SetTenancy(id string)

SetTenancy sets the root compartment that owns repositories created by a first push.

func (*InMemoryBackend) Snapshot

func (b *InMemoryBackend) Snapshot(ctx context.Context) []byte

Snapshot serialises every resource and the registered API keys. Image blobs and manifests are not part of it: they live under the data directory when one is configured.

func (*InMemoryBackend) SplitRegistryName

func (b *InMemoryBackend) SplitRegistryName(name string) (string, bool)

SplitRegistryName strips the namespace from a registry repository name.

func (*InMemoryBackend) UpdateContainerConfiguration

func (b *InMemoryBackend) UpdateContainerConfiguration(
	compartment, ifMatch string, in updateConfigIn,
) (configWire, string, error)

UpdateContainerConfiguration changes the container configuration.

func (*InMemoryBackend) UpdateContainerImage

func (b *InMemoryBackend) UpdateContainerImage(id, ifMatch string, in updateTagsIn) (imageWire, string, error)

UpdateContainerImage changes an image's tags.

func (*InMemoryBackend) UpdateContainerImageSignature

func (b *InMemoryBackend) UpdateContainerImageSignature(
	id, ifMatch string, in updateTagsIn,
) (signatureWire, string, error)

UpdateContainerImageSignature changes a signature's tags.

func (*InMemoryBackend) UpdateContainerRepository

func (b *InMemoryBackend) UpdateContainerRepository(id, ifMatch string, in updateRepoIn) (repoWire, string, error)

UpdateContainerRepository changes the mutable attributes of a repository.

func (*InMemoryBackend) UpdateGenericArtifact

func (b *InMemoryBackend) UpdateGenericArtifact(
	id, ifMatch string,
	in updateTagsIn,
) (genericArtifactWire, string, error)

UpdateGenericArtifact changes an artifact's tags.

func (*InMemoryBackend) UpdateGenericArtifactByPath

func (b *InMemoryBackend) UpdateGenericArtifactByPath(
	repoID, path, version, ifMatch string, in updateTagsIn,
) (genericArtifactWire, string, error)

UpdateGenericArtifactByPath changes an artifact's tags.

func (*InMemoryBackend) UpdateRepository

func (b *InMemoryBackend) UpdateRepository(
	id, ifMatch string,
	in updateGenericRepoIn,
) (genericRepoWire, string, error)

UpdateRepository changes a generic repository's name, description and tags.

func (*InMemoryBackend) ValidLogin

func (b *InMemoryBackend) ValidLogin(username, password string) (string, bool)

ValidLogin accepts `<namespace>/<user>` with any non-empty auth token and returns the user part. Auth tokens are not stored by OCI Identity, so there is nothing to compare the password with.

type Layer

type Layer struct {
	TimeCreated time.Time `json:"timeCreated"`
	Digest      string    `json:"digest"`
	Size        int64     `json:"size"`
}

Layer is one blob of an image.

type ListOpts

type ListOpts struct {
	SortBy  string
	Order   string
	Page    string
	Limit   int
	Subtree bool
}

ListOpts carries the shared list query parameters.

type Provider

type Provider struct{}

Provider implements service.Provider for OCI Artifacts. It runs on its own listener (see Handler.StartWorker) and never matches on the shared AWS router.

func (*Provider) Init

Init creates the backend and handler; the port is bound in StartWorker.

func (*Provider) Name

func (p *Provider) Name() string

Name returns the service provider name.

type Readme

type Readme struct {
	Content string `json:"content"`
	Format  string `json:"format"`
}

Readme is a container repository's README.

type Repo

type Repo struct {
	TimeCreated    time.Time  `json:"timeCreated"`
	TimeLastPushed *time.Time `json:"timeLastPushed,omitempty"`
	Readme         *Readme    `json:"readme,omitempty"`
	Tags           Tags       `json:"tags"`
	ID             string     `json:"id"`
	Name           string     `json:"name"`
	CompartmentID  string     `json:"compartmentId"`
	CreatedBy      string     `json:"createdBy"`
	Etag           string     `json:"etag"`
	Seq            int64      `json:"seq"`
	IsImmutable    bool       `json:"isImmutable"`
	IsPublic       bool       `json:"isPublic"`
}

Repo is a container repository.

type Scope

type Scope struct {
	Name    string
	Actions []string
}

Scope is one `repository:<name>:<actions>` grant.

func ParseScope

func ParseScope(raw string) (Scope, bool)

ParseScope parses `repository:<name>:<action>[,<action>]`; other resource types are not supported.

func (Scope) String

func (s Scope) String() string

type Settings

type Settings struct {
	Port int `` //nolint:lll // config struct tags are intentionally verbose
	/* 274-byte string literal not displayed */
	EnforceAuth bool `` //nolint:lll // config struct tags are intentionally verbose
	/* 317-byte string literal not displayed */
}

Settings holds service-level configuration, embedded in the root CLI as CLI.OCIArtifacts.

func DefaultSettings

func DefaultSettings() Settings

DefaultSettings returns the settings used when no ConfigProvider is available.

type Signature

type Signature struct {
	TimeCreated     time.Time `json:"timeCreated"`
	Tags            Tags      `json:"tags"`
	ID              string    `json:"id"`
	ImageID         string    `json:"imageId"`
	CompartmentID   string    `json:"compartmentId"`
	CreatedBy       string    `json:"createdBy"`
	KmsKeyID        string    `json:"kmsKeyId"`
	KmsKeyVersionID string    `json:"kmsKeyVersionId"`
	Message         string    `json:"message"`
	Signature       string    `json:"signature"`
	Algorithm       string    `json:"signingAlgorithm"`
	Etag            string    `json:"etag"`
	Seq             int64     `json:"seq"`
}

Signature is a container image signature.

type Tags

type Tags struct {
	FreeformTags map[string]string         `json:"freeformTags,omitempty"`
	DefinedTags  map[string]map[string]any `json:"definedTags,omitempty"`
}

Tags are the shared freeform and defined tag sets of a resource.

type Version

type Version struct {
	TimeCreated time.Time `json:"timeCreated"`
	Version     string    `json:"version"`
	CreatedBy   string    `json:"createdBy"`
}

Version is a tag of an image.

Jump to

Keyboard shortcuts

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