Documentation
¶
Overview ¶
Package file provides implementation of a content store based on file system.
Example (PackFiles) ¶
Example_packFiles gives an example of adding files and generating a manifest referencing the files.
store, err := file.New(workingDir)
if err != nil {
panic(err)
}
defer store.Close()
ctx := context.Background()
// 1. Add files into the file store
mediaType := "example/file"
fileNames := []string{"foo.txt", "bar.txt"}
fileDescriptors := make([]ocispec.Descriptor, 0, len(fileNames))
for _, name := range fileNames {
fileDescriptor, err := store.Add(ctx, name, mediaType, "")
if err != nil {
panic(err)
}
fileDescriptors = append(fileDescriptors, fileDescriptor)
fmt.Printf("file descriptor for %s: %v\n", name, fileDescriptor)
}
// 2. Generate a manifest referencing the files
artifactType := "example/test"
manifestDescriptor, err := oras.Pack(ctx, store, artifactType, fileDescriptors, oras.PackOptions{})
if err != nil {
panic(err)
}
fmt.Println("manifest media type:", manifestDescriptor.MediaType)
Output: file descriptor for foo.txt: {example/file sha256:2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae 3 [] map[org.opencontainers.image.title:foo.txt] [] <nil> } file descriptor for bar.txt: {example/file sha256:fcde2b2edba56bf408601fb721fe9b5c338d10ee429ea04fae5511b68fbf8fb9 3 [] map[org.opencontainers.image.title:bar.txt] [] <nil> } manifest media type: application/vnd.oci.artifact.manifest.v1+json
Index ¶
- Constants
- Variables
- type Store
- func (s *Store) Add(_ context.Context, name, mediaType, path string) (ocispec.Descriptor, error)
- func (s *Store) Close() error
- func (s *Store) Exists(ctx context.Context, target ocispec.Descriptor) (bool, error)
- func (s *Store) Fetch(ctx context.Context, target ocispec.Descriptor) (io.ReadCloser, error)
- func (s *Store) Predecessors(ctx context.Context, node ocispec.Descriptor) ([]ocispec.Descriptor, error)
- func (s *Store) Push(ctx context.Context, expected ocispec.Descriptor, content io.Reader) error
- func (s *Store) Resolve(ctx context.Context, ref string) (ocispec.Descriptor, error)
- func (s *Store) Tag(ctx context.Context, desc ocispec.Descriptor, ref string) error
Examples ¶
Constants ¶
const ( // AnnotationDigest is the annotation key for the digest of the uncompressed content. AnnotationDigest = "io.deis.oras.content.digest" // AnnotationUnpack is the annotation key for indication of unpacking. AnnotationUnpack = "io.deis.oras.content.unpack" )
Variables ¶
Functions ¶
This section is empty.
Types ¶
type Store ¶
type Store struct {
// TarReproducible controls if the tarballs generated
// for the added directories are reproducible.
// When specified, some metadata such as change time
// will be removed from the files in the tarballs. Default value: false.
TarReproducible bool
// AllowPathTraversalOnWrite controls if path traversal is allowed
// when writing files. When specified, writing files
// outside the working directory will be allowed. Default value: false.
AllowPathTraversalOnWrite bool
// DisableOverwrite controls if push operations can overwrite existing files.
// When specified, saving files to existing paths will be disabled.
// Default value: false.
DisableOverwrite bool
// ForceCAS controls if files with same content but different names are
// deduped after push operations. When a DAG is copied between CAS
// targets, nodes are deduped by content. By default, file store restores
// deduped successor files after a node is copied. This may result in two
// files with identical content. If this is not the desired behavior,
// ForceCAS can be specified to enforce CAS style dedup.
// Default value: false.
ForceCAS bool
// IgnoreNoName controls if push operations should ignore descriptors
// without a name. When specified, corresponding content will be discarded.
// Otherwise, content will be saved to a fallback storage.
// A typical scenario is pulling an arbitrary artifact masqueraded as OCI
// image to file store. This option can be specified to discard unnamed
// manifest and config file, while leaving only named layer files.
// Default value: false.
IgnoreNoName bool
// SkipUnpack controls if push operations should skip unpacking files. This
// value overrides the [AnnotationUnpack].
// Default value: false.
SkipUnpack bool
// contains filtered or unexported fields
}
Store represents a file system based store, which implements `oras.Target`.
In the file store, the contents described by names are location-addressed by file paths. Meanwhile, the file paths are mapped to a virtual CAS where all metadata are stored in the memory.
The contents that are not described by names are stored in a fallback storage, which is a limited memory CAS by default. As all the metadata are stored in the memory, the file store cannot be restored from the file system.
After use, the file store needs to be closed by calling the Store.Close function. The file store cannot be used after being closed.
func New ¶
New creates a file store, using a default limited memory CAS as the fallback storage for contents without names. When pushing content without names, the size of content being pushed cannot exceed the default size limit: 4 MiB.
func NewWithFallbackLimit ¶
NewWithFallbackLimit creates a file store, using a default limited memory CAS as the fallback storage for contents without names. When pushing content without names, the size of content being pushed cannot exceed the size limit specified by the `limit` parameter.
func NewWithFallbackStorage ¶
NewWithFallbackStorage creates a file store, using the provided fallback storage for contents without names.
func (*Store) Close ¶
Close closes the file store and cleans up all the temporary files used by it. The store cannot be used after being closed. This function is not go-routine safe.
func (*Store) Fetch ¶
func (s *Store) Fetch(ctx context.Context, target ocispec.Descriptor) (io.ReadCloser, error)
Fetch fetches the content identified by the descriptor.
func (*Store) Predecessors ¶
func (s *Store) Predecessors(ctx context.Context, node ocispec.Descriptor) ([]ocispec.Descriptor, error)
Predecessors returns the nodes directly pointing to the current node. Predecessors returns nil without error if the node does not exists in the store.
func (*Store) Push ¶
Push pushes the content, matching the expected descriptor. If name is not specified in the descriptor, the content will be pushed to the fallback storage by default, or will be discarded when Store.IgnoreNoName is true.
Source Files