Skip to content
This repository was archived by the owner on Jan 15, 2026. It is now read-only.

Commit 0c9e84e

Browse files
wkingwking
committed
image/cas: Add a generic CAS interface
And implement that interface for tarballs based on the specs image-layout. I plan on adding other backends and methods later, but this is enough for a proof of concept getter. Also add a new 'oci-image-tool cas get ...' subcommand so folks can access the new read functionality from the command line. In a subsequent commit, I'll replace the image/walker.go functionality with this new API. The Context interface follows the pattern recommended in [1], allowing callers to cancel long running actions (e.g. push/pull over the network for engine implementations that communicate with a remote store). Passing a Context instance along to NewEngine gives us a way to cancel engine initialization which happens to take too long. That's unlikely to happen for NewTarEngine, but it's easy enough to pass it on down just in case. blobPath's separator argument will allow us to use string(os.PathSeparator)) once we add directory support. [1]: https://blog.golang.org/context Signed-off-by: W. Trevor King <[email protected]>
1 parent 2b3754c commit 0c9e84e

File tree

7 files changed

+301
-0
lines changed

7 files changed

+301
-0
lines changed

‎cmd/oci-image-tool/cas-get.go‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
// Copyright 2016 The Linux Foundation
2+
//
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+
package main
16+
17+
import (
18+
"fmt"
19+
"io/ioutil"
20+
"os"
21+
22+
"github.com/opencontainers/go-digest"
23+
"github.com/opencontainers/image-tools/image/cas/layout"
24+
"github.com/urfave/cli"
25+
"golang.org/x/net/context"
26+
)
27+
28+
type casGetCmd struct {
29+
path string
30+
digest digest.Digest
31+
}
32+
33+
var casGetCommand = cli.Command{
34+
Name: "get",
35+
Usage: "Retrieve a blob from the store and write it to stdout.",
36+
ArgsUsage: "PATH DIGEST",
37+
Action: casGetHandle,
38+
}
39+
40+
func casGetHandle(ctx *cli.Context) (err error) {
41+
if ctx.NArg() != 2 {
42+
return fmt.Errorf("both PATH and DIGEST must be provided")
43+
}
44+
45+
state := &casGetCmd{}
46+
state.path = ctx.Args().Get(0)
47+
state.digest, err = digest.Parse(ctx.Args().Get(1))
48+
if err != nil {
49+
return err
50+
}
51+
52+
engineContext := context.Background()
53+
54+
engine, err := layout.NewEngine(engineContext, state.path)
55+
if err != nil {
56+
return err
57+
}
58+
defer engine.Close()
59+
60+
reader, err := engine.Get(engineContext, state.digest)
61+
if err != nil {
62+
return err
63+
}
64+
defer reader.Close()
65+
66+
bytes, err := ioutil.ReadAll(reader)
67+
if err != nil {
68+
return err
69+
}
70+
71+
n, err := os.Stdout.Write(bytes)
72+
if err != nil {
73+
return err
74+
}
75+
if n < len(bytes) {
76+
return fmt.Errorf("wrote %d of %d bytes", n, len(bytes))
77+
}
78+
79+
return nil
80+
}

‎cmd/oci-image-tool/cas.go‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
// Copyright 2016 The Linux Foundation
2+
//
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+
package main
16+
17+
import (
18+
"github.com/urfave/cli"
19+
)
20+
21+
func casHandle(context *cli.Context) error {
22+
return cli.ShowCommandHelp(context, context.Command.Name)
23+
}
24+
25+
var casCommand = cli.Command{
26+
Name: "cas",
27+
Usage: "Content-addressable storage manipulation",
28+
Action: casHandle,
29+
Subcommands: []cli.Command{
30+
casGetCommand,
31+
},
32+
}

‎cmd/oci-image-tool/main.go‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,7 @@ func main() {
5252
validateCommand,
5353
unpackCommand,
5454
createCommand,
55+
casCommand,
5556
}
5657

5758
if err := app.Run(os.Args); err != nil {

‎image/cas/interface.go‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
// Copyright 2016 The Linux Foundation
2+
//
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+
// Package cas implements generic content-addressable storage.
16+
package cas
17+
18+
import (
19+
"io"
20+
21+
"github.com/opencontainers/go-digest"
22+
"golang.org/x/net/context"
23+
)
24+
25+
// Engine represents a content-addressable storage engine.
26+
type Engine interface {
27+
// Get returns a reader for retrieving a blob from the store.
28+
// Returns os.ErrNotExist if the digest is not found.
29+
Get(ctx context.Context, digest digest.Digest) (reader io.ReadCloser, err error)
30+
31+
// Close releases resources held by the engine. Subsequent engine
32+
// method calls will fail.
33+
Close() (err error)
34+
}

‎image/cas/layout/interface.go‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
// Copyright 2016 The Linux Foundation
2+
//
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+
package layout
16+
17+
import (
18+
"io"
19+
)
20+
21+
// ReadWriteSeekCloser wraps the Read, Write, Seek, and Close methods.
22+
type ReadWriteSeekCloser interface {
23+
io.ReadWriteSeeker
24+
io.Closer
25+
}

‎image/cas/layout/main.go‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
// Copyright 2016 The Linux Foundation
2+
//
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+
// Package layout implements the cas interface using the image-spec's
16+
// image-layout [1].
17+
//
18+
// [1]: https://github.com/opencontainers/image-spec/blob/master/image-layout.md
19+
package layout
20+
21+
import (
22+
"os"
23+
"strings"
24+
25+
"github.com/opencontainers/go-digest"
26+
"github.com/opencontainers/image-tools/image/cas"
27+
"golang.org/x/net/context"
28+
)
29+
30+
// NewEngine instantiates an engine with the appropriate backend (tar,
31+
// HTTP, ...).
32+
func NewEngine(ctx context.Context, path string) (engine cas.Engine, err error) {
33+
file, err := os.Open(path)
34+
if err != nil {
35+
return nil, err
36+
}
37+
38+
return NewTarEngine(ctx, file)
39+
}
40+
41+
// blobPath returns the PATH to the DIGEST blob. SEPARATOR selects
42+
// the path separator used between components.
43+
func blobPath(digest digest.Digest, separator string) (path string, err error) {
44+
err = digest.Validate()
45+
if err != nil {
46+
return "", err
47+
}
48+
algorithm := digest.Algorithm().String()
49+
components := []string{".", "blobs", algorithm, digest.Hex()}
50+
return strings.Join(components, separator), nil
51+
}

‎image/cas/layout/tar.go‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
// Copyright 2016 The Linux Foundation
2+
//
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+
package layout
16+
17+
import (
18+
"archive/tar"
19+
"io"
20+
"io/ioutil"
21+
"os"
22+
23+
"github.com/opencontainers/go-digest"
24+
"github.com/opencontainers/image-tools/image/cas"
25+
"golang.org/x/net/context"
26+
)
27+
28+
// TarEngine is a cas.Engine backed by a tar file.
29+
type TarEngine struct {
30+
file ReadWriteSeekCloser
31+
}
32+
33+
// NewTarEngine returns a new TarEngine.
34+
func NewTarEngine(ctx context.Context, file ReadWriteSeekCloser) (engine cas.Engine, err error) {
35+
engine = &TarEngine{
36+
file: file,
37+
}
38+
39+
return engine, nil
40+
}
41+
42+
// Get returns a reader for retrieving a blob from the store.
43+
func (engine *TarEngine) Get(ctx context.Context, digest digest.Digest) (reader io.ReadCloser, err error) {
44+
targetName, err := blobPath(digest, "/")
45+
if err != nil {
46+
return nil, err
47+
}
48+
49+
_, err = engine.file.Seek(0, io.SeekStart)
50+
if err != nil {
51+
return nil, err
52+
}
53+
54+
tarReader := tar.NewReader(engine.file)
55+
for {
56+
select {
57+
case <-ctx.Done():
58+
return nil, ctx.Err()
59+
default:
60+
}
61+
62+
header, err := tarReader.Next()
63+
if err == io.EOF {
64+
return nil, os.ErrNotExist
65+
} else if err != nil {
66+
return nil, err
67+
}
68+
69+
if header.Name == targetName {
70+
return ioutil.NopCloser(tarReader), nil
71+
}
72+
}
73+
}
74+
75+
// Close releases resources held by the engine.
76+
func (engine *TarEngine) Close() (err error) {
77+
return engine.file.Close()
78+
}

0 commit comments

Comments
 (0)