github.com/opcr-io/oras-go/v2@v2.0.0-20231122155130-eb4260d8a0ae/content/storage.go (about)

     1  /*
     2  Copyright The ORAS Authors.
     3  Licensed under the Apache License, Version 2.0 (the "License");
     4  you may not use this file except in compliance with the License.
     5  You may obtain a copy of the License at
     6  
     7  http://www.apache.org/licenses/LICENSE-2.0
     8  
     9  Unless required by applicable law or agreed to in writing, software
    10  distributed under the License is distributed on an "AS IS" BASIS,
    11  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    12  See the License for the specific language governing permissions and
    13  limitations under the License.
    14  */
    15  
    16  package content
    17  
    18  import (
    19  	"context"
    20  	"io"
    21  
    22  	ocispec "github.com/opencontainers/image-spec/specs-go/v1"
    23  )
    24  
    25  // Fetcher fetches content.
    26  type Fetcher interface {
    27  	// Fetch fetches the content identified by the descriptor.
    28  	Fetch(ctx context.Context, target ocispec.Descriptor) (io.ReadCloser, error)
    29  }
    30  
    31  // Pusher pushes content.
    32  type Pusher interface {
    33  	// Push pushes the content, matching the expected descriptor.
    34  	// Reader is perferred to Writer so that the suitable buffer size can be
    35  	// chosen by the underlying implementation. Furthermore, the implementation
    36  	// can also do reflection on the Reader for more advanced I/O optimization.
    37  	Push(ctx context.Context, expected ocispec.Descriptor, content io.Reader) error
    38  }
    39  
    40  // Storage represents a content-addressable storage (CAS) where contents are
    41  // accessed via Descriptors.
    42  // The storage is designed to handle blobs of large sizes.
    43  type Storage interface {
    44  	ReadOnlyStorage
    45  	Pusher
    46  }
    47  
    48  // DeleteStorage represents an extension of the Storage interface that includes the Deleter.
    49  type DeleteStorage interface {
    50  	Storage
    51  	Deleter
    52  }
    53  
    54  // ReadOnlyStorage represents a read-only Storage.
    55  type ReadOnlyStorage interface {
    56  	Fetcher
    57  
    58  	// Exists returns true if the described content exists.
    59  	Exists(ctx context.Context, target ocispec.Descriptor) (bool, error)
    60  }
    61  
    62  // Deleter removes content.
    63  // Deleter is an extension of Storage.
    64  type Deleter interface {
    65  	// Delete removes the content identified by the descriptor.
    66  	Delete(ctx context.Context, target ocispec.Descriptor) error
    67  }
    68  
    69  // FetchAll safely fetches the content described by the descriptor.
    70  // The fetched content is verified against the size and the digest.
    71  func FetchAll(ctx context.Context, fetcher Fetcher, desc ocispec.Descriptor) ([]byte, error) {
    72  	rc, err := fetcher.Fetch(ctx, desc)
    73  	if err != nil {
    74  		return nil, err
    75  	}
    76  	defer rc.Close()
    77  	return ReadAll(rc, desc)
    78  }
    79  
    80  // FetcherFunc is the basic Fetch method defined in Fetcher.
    81  type FetcherFunc func(ctx context.Context, target ocispec.Descriptor) (io.ReadCloser, error)
    82  
    83  // Fetch performs Fetch operation by the FetcherFunc.
    84  func (fn FetcherFunc) Fetch(ctx context.Context, target ocispec.Descriptor) (io.ReadCloser, error) {
    85  	return fn(ctx, target)
    86  }