Basic implementations of layout functions for tlog-tiles

api/layout/paths.go

@@ -0,0 +1,58 @@
+// Copyright 2024 Google LLC. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Package layout contains routines for specifying the path layout of Tessera logs,
+// which is really to say that it provides functions to calculate paths used by the
+// tlog-tiles API: https://github.com/C2SP/C2SP/blob/main/tlog-tiles.md
+package layout
+
+import (
+	"fmt"
+	"path/filepath"
+)
+
+const (
+	// CheckpointPath is the location of the file containing the log checkpoint.
+	CheckpointPath = "checkpoint"
+)
+
+// EntriesPath builds the local path at which the leaf with the given index lives in.
+// Note that this will be an entry bundle containing up to 256 entries and thus multiple
+// indices can map to the same output path.
+//
+// TODO(mhutchinson): revisit to consider how partial tile suffixes should be added.
+func EntriesPath(seq uint64) string {
+	seq = seq / 256
+	frag := []string{
+		"tile",
+		"entries",
+		fmt.Sprintf("x%03x", (seq>>16)&0xff),
+		fmt.Sprintf("x%03x", (seq>>8)&0xff),
+		fmt.Sprintf("%03x", seq&0xff),
+	}
+	return filepath.Join(frag...)
+}
+
+// TilePath builds the path to the subtree tile with the given level and index.
+func TilePath(level, index uint64) string {
+	seq := index / 256
+	frag := []string{
+		"tile",
+		fmt.Sprintf("%d", level),
+		fmt.Sprintf("x%03x", (seq>>16)&0xff),
+		fmt.Sprintf("x%03x", (seq>>8)&0xff),
+		fmt.Sprintf("%03x", seq&0xff),
+	}
+	return filepath.Join(frag...)
+}

api/layout/paths_test.go

@@ -0,0 +1,75 @@
+// Copyright 2024 Google LLC. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package layout
+
+import (
+	"fmt"
+	"testing"
+)
+
+func TestEntriesPath(t *testing.T) {
+	for _, test := range []struct {
+		seq      uint64
+		wantPath string
+	}{
+		{
+			seq:      0,
+			wantPath: "tile/entries/x000/x000/000",
+		}, {
+			seq:      255,
+			wantPath: "tile/entries/x000/x000/000",
+		}, {
+			seq:      256,
+			wantPath: "tile/entries/x000/x000/001",
+		}, {
+			seq:      0xffeeddccbb,
+			wantPath: "tile/entries/x0ee/x0dd/0cc",
+		},
+	} {
+		desc := fmt.Sprintf("seq %d", test.seq)
+		t.Run(desc, func(t *testing.T) {
+			gotPath := EntriesPath(test.seq)
+			if gotPath != test.wantPath {
+				t.Errorf("got file %q want %q", gotPath, test.wantPath)
+			}
+		})
+	}
+}
+
+func TestTilePath(t *testing.T) {
+	for _, test := range []struct {
+		level    uint64
+		index    uint64
+		wantPath string
+	}{
+		{
+			level:    0,
+			index:    0,
+			wantPath: "tile/0/x000/x000/000",
+		}, {
+			level:    15,
+			index:    0x455667,
+			wantPath: "tile/15/x000/x045/056",
+		},
+	} {
+		desc := fmt.Sprintf("level %x index %x", test.level, test.index)
+		t.Run(desc, func(t *testing.T) {
+			gotPath := TilePath(test.level, test.index)
+			if gotPath != test.wantPath {
+				t.Errorf("Got path %q want %q", gotPath, test.wantPath)
+			}
+		})
+	}
+}

api/layout/tile.go

@@ -0,0 +1,38 @@
+// Copyright 2024 Google LLC. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package layout
+
+// PartialTileSize returns the expected number of leaves in a tile at the given location within
+// a tree of the specified logSize, or 0 if the tile is expected to be fully populated.
+func PartialTileSize(level, index, logSize uint64) uint64 {
+	sizeAtLevel := logSize >> (level * 8)
+	fullTiles := sizeAtLevel / 256
+	if index < fullTiles {
+		return 0
+	}
+	return sizeAtLevel % 256
+}
+
+// NodeCoordsToTileAddress returns the (TileLevel, TileIndex) in tile-space, and the
+// (NodeLevel, NodeIndex) address within that tile of the specified tree node co-ordinates.
+func NodeCoordsToTileAddress(treeLevel, treeIndex uint64) (uint64, uint64, uint, uint64) {
+	tileRowWidth := uint64(1 << (8 - treeLevel%8))
+	tileLevel := treeLevel / 8
+	tileIndex := treeIndex / tileRowWidth
+	nodeLevel := uint(treeLevel % 8)
+	nodeIndex := uint64(treeIndex % tileRowWidth)
+
+	return tileLevel, tileIndex, nodeLevel, nodeIndex
+}

api/layout/tile_test.go

@@ -0,0 +1,84 @@
+// Copyright 2024 Google LLC. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package layout
+
+import (
+	"fmt"
+	"testing"
+)
+
+func TestNodeCoordsToTileAddress(t *testing.T) {
+	for _, test := range []struct {
+		treeLevel     uint64
+		treeIndex     uint64
+		wantTileLevel uint64
+		wantTileIndex uint64
+		wantNodeLevel uint
+		wantNodeIndex uint64
+	}{
+		{
+			treeLevel:     0,
+			treeIndex:     0,
+			wantTileLevel: 0,
+			wantTileIndex: 0,
+			wantNodeLevel: 0,
+			wantNodeIndex: 0,
+		}, {
+			treeLevel:     0,
+			treeIndex:     255,
+			wantTileLevel: 0,
+			wantTileIndex: 0,
+			wantNodeLevel: 0,
+			wantNodeIndex: 255,
+		}, {
+			treeLevel:     0,
+			treeIndex:     256,
+			wantTileLevel: 0,
+			wantTileIndex: 1,
+			wantNodeLevel: 0,
+			wantNodeIndex: 0,
+		}, {
+			treeLevel:     1,
+			treeIndex:     0,
+			wantTileLevel: 0,
+			wantTileIndex: 0,
+			wantNodeLevel: 1,
+			wantNodeIndex: 0,
+		}, {
+			treeLevel:     8,
+			treeIndex:     0,
+			wantTileLevel: 1,
+			wantTileIndex: 0,
+			wantNodeLevel: 0,
+			wantNodeIndex: 0,
+		},
+	} {
+		t.Run(fmt.Sprintf("%d-%d", test.treeLevel, test.treeIndex), func(t *testing.T) {
+			tl, ti, nl, ni := NodeCoordsToTileAddress(test.treeLevel, test.treeIndex)
+			if got, want := tl, test.wantTileLevel; got != want {
+				t.Errorf("Got TileLevel %d want %d", got, want)
+			}
+			if got, want := ti, test.wantTileIndex; got != want {
+				t.Errorf("Got TileIndex %d want %d", got, want)
+			}
+			if got, want := nl, test.wantNodeLevel; got != want {
+				t.Errorf("Got NodeLevel %d want %d", got, want)
+			}
+			if got, want := ni, test.wantNodeIndex; got != want {
+				t.Errorf("Got NodeIndex %d want %d", got, want)
+			}
+		})
+	}
+}