metadata

type Storage interface {
	// GetMetadata fetches metadata associated with the given prefix and all
	// parent prefixes.
	//
	// The prefix may be an empty string, in which case the root metadata will be
	// returned, if it is defined.
	//
	// Does not check permissions.
	//
	// The return value is sorted by the prefix length. Prefixes without metadata
	// are skipped. For example, when requesting metadata for prefix "a/b/c/d" the
	// return value may contain entries for "", "a", "a/b", "a/b/c/d" (in that
	// order, where "" indicates the root and "a/b/c" is skipped in this example
	// as not having any metadata attached).
	//
	// Note that the prefix of the last entry doesn't necessary match 'prefix'.
	// This happens if metadata for that prefix doesn't exist. Similarly, the
	// returns value may be completely empty slice in case there's no metadata
	// for the requested prefix and all its parent prefixes.
	//
	// Returns a fatal error if the prefix is malformed, all other errors are
	// transient.
	GetMetadata(ctx context.Context, prefix string) ([]*api.PrefixMetadata, error)

	// VisitMetadata enumerates the metadata in depth-first order.
	//
	// Can be used to fetch all metadata items at and under the given prefix.
	//
	// The callback is called for each visited node (always starting from 'prefix'
	// itself, even if it has no metadata directly attached to it), receiving same
	// metadata list as if GetMetadata was used to fetch it. The callback can
	// decide whether to proceed with the enumeration of the corresponding subtree
	// or skip it (by returning either true or false).
	//
	// Aborts the traversal on a first error from the callback.
	//
	// Returns either a transient error if fetching failed, or whatever error the
	// callback returned.
	VisitMetadata(ctx context.Context, prefix string, cb Visitor) error

	// UpdateMetadata transactionally (with XG transaction) updates or creates
	// metadata of some prefix and returns it.
	//
	// The prefix may be an empty string, in which case the root metadata will
	// be updated, if allowed.
	//
	// Does not check permissions. Does not check the format of the updated
	// metadata.
	//
	// It fetches the metadata object and calls the callback to modify it. The
	// callback may be called multiple times when retrying the transaction. If the
	// callback mutates the metadata and doesn't return an error, the metadata's
	// fingerprint is updated, the metadata is saved to the storage and returned
	// to the caller.
	//
	// If the metadata object doesn't exist yet, the callback will be called with
	// an empty object that has only 'Prefix' field populated. The callback then
	// can populate the rest of the fields. If it doesn't touch any fields
	// (but still succeeds), UpdateMetadata will return nil PrefixMetadata, to
	// indicate the metadata is still absent.
	//
	// If the callback returns an error, it will be returned as is. If the
	// transaction itself fails, returns a transient error.
	UpdateMetadata(ctx context.Context, prefix string, cb func(ctx context.Context, m *api.PrefixMetadata) error) (*api.PrefixMetadata, error)
}

type Visitor func(prefix string, md []*api.PrefixMetadata) (cont bool, err error)