github.com/letsencrypt/trillian@v1.1.2-0.20180615153820-ae375a99d36a/storage/map_storage.go (about)

     1  // Copyright 2016 Google Inc. All Rights Reserved.
     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 storage
    16  
    17  import (
    18  	"context"
    19  
    20  	"github.com/google/trillian"
    21  )
    22  
    23  // ReadOnlyMapTX provides a read-only view into log data.
    24  // A ReadOnlyMapTX, unlike ReadOnlyMapTreeTX, is not tied to a particular tree.
    25  type ReadOnlyMapTX interface {
    26  	// Commit ensures the data read by the TX is consistent in the database. Only after Commit the
    27  	// data read should be regarded as valid.
    28  	Commit() error
    29  
    30  	// Rollback discards the read-only TX.
    31  	Rollback() error
    32  
    33  	// Close attempts to Rollback the TX if it's open, it's a noop otherwise.
    34  	Close() error
    35  }
    36  
    37  // ReadOnlyMapTreeTX provides a read-only view into the Map data.
    38  // A ReadOnlyMapTreeTX can only read from the tree specified in its creation.
    39  type ReadOnlyMapTreeTX interface {
    40  	ReadOnlyTreeTX
    41  
    42  	// GetSignedMapRoot returns the SignedMapRoot associated with the
    43  	// specified revision.
    44  	GetSignedMapRoot(ctx context.Context, revision int64) (trillian.SignedMapRoot, error)
    45  	// LatestSignedMapRoot returns the most recently created SignedMapRoot.
    46  	LatestSignedMapRoot(ctx context.Context) (trillian.SignedMapRoot, error)
    47  
    48  	// Get retrieves the values associated with the keyHashes, if any, at the
    49  	// specified revision.
    50  	// Setting revision to -1 will fetch the latest revision.
    51  	// The returned array of MapLeaves will only contain entries for which values
    52  	// exist.  i.e. requesting a set of unknown keys would result in a
    53  	// zero-length array being returned.
    54  	Get(ctx context.Context, revision int64, keyHashes [][]byte) ([]trillian.MapLeaf, error)
    55  }
    56  
    57  // MapTreeTX is the transactional interface for reading/modifying a Map.
    58  // It extends the basic TreeTX interface with Map specific methods.
    59  // After a call to Commit or Rollback implementations must be in a clean state and have
    60  // released any resources owned by the MapTX.
    61  // A MapTreeTX can only read from the tree specified in its creation.
    62  type MapTreeTX interface {
    63  	ReadOnlyMapTreeTX
    64  	TreeWriter
    65  
    66  	// StoreSignedMapRoot stores root.
    67  	StoreSignedMapRoot(ctx context.Context, root trillian.SignedMapRoot) error
    68  	// Set sets key to leaf
    69  	Set(ctx context.Context, keyHash []byte, value trillian.MapLeaf) error
    70  }
    71  
    72  // ReadOnlyMapStorage provides a narrow read-only view into a MapStorage.
    73  type ReadOnlyMapStorage interface {
    74  	DatabaseChecker
    75  
    76  	// Snapshot starts a read-only transaction not tied to any particular tree.
    77  	Snapshot(ctx context.Context) (ReadOnlyMapTX, error)
    78  
    79  	// SnapshotForTree starts a new read-only transaction.
    80  	// Commit must be called when the caller is finished with the returned object,
    81  	// and values read through it should only be propagated if Commit returns
    82  	// without error.
    83  	SnapshotForTree(ctx context.Context, tree *trillian.Tree) (ReadOnlyMapTreeTX, error)
    84  }
    85  
    86  // MapTXFunc is the func signature for passing into ReadWriteTransaction.
    87  type MapTXFunc func(context.Context, MapTreeTX) error
    88  
    89  // MapStorage should be implemented by concrete storage mechanisms which want to support Maps
    90  type MapStorage interface {
    91  	ReadOnlyMapStorage
    92  
    93  	// ReadWriteTransaction starts a RW transaction on the underlying storage, and
    94  	// calls f with it.
    95  	// If f fails and returns an error, the storage implementation may optionally
    96  	// retry with a new transaction, and f MUST NOT keep state across calls.
    97  	ReadWriteTransaction(ctx context.Context, tree *trillian.Tree, f MapTXFunc) error
    98  }