1	package index
     2	
     3	import (
     4		"context"
     5		"sync"
     6		"time"
     7	
     8		"perkeep.org/pkg/blob"
     9		"perkeep.org/pkg/types/camtypes"
    10	)
    11	
    12	type Interface interface {
    13		sync.Locker
    14		RLock()
    15		RUnlock()
    16	
    17		// os.ErrNotExist should be returned if the blob isn't known
    18		GetBlobMeta(context.Context, blob.Ref) (camtypes.BlobMeta, error)
    19	
    20		// Should return os.ErrNotExist if not found.
    21		GetFileInfo(ctx context.Context, fileRef blob.Ref) (camtypes.FileInfo, error)
    22	
    23		// Should return os.ErrNotExist if not found.
    24		GetImageInfo(ctx context.Context, fileRef blob.Ref) (camtypes.ImageInfo, error)
    25	
    26		// Should return os.ErrNotExist if not found.
    27		GetMediaTags(ctx context.Context, fileRef blob.Ref) (map[string]string, error)
    28	
    29		// GetFileLocation returns the location info (currently Exif) of the fileRef.
    30		// Should return os.ErrNotExist if fileRef is not found,
    31		// is not a file, or it has no location info.
    32		GetFileLocation(ctx context.Context, fileRef blob.Ref) (camtypes.Location, error)
    33	
    34		// KeyId returns the GPG keyid (e.g. "2931A67C26F5ABDA)
    35		// given the blobref of its ASCII-armored blobref.
    36		// The error is ErrNotFound if not found.
    37		KeyId(context.Context, blob.Ref) (string, error)
    38	
    39		// AppendClaims appends to dst claims on the given permanode.
    40		// The signerFilter - a GPG key ID (e.g. "2931A67C26F5ABDA) -
    41		// and attrFilter are both optional.  If non-zero,
    42		// they filter the return items to only claims made by the given signer
    43		// or claims about the given attribute, respectively.
    44		// Deleted claims are never returned.
    45		// The items may be appended in any order.
    46		//
    47		// TODO: this should take a context and a callback func
    48		// instead of a dst, then it can append to a channel instead,
    49		// and the context lets it be interrupted. The callback should
    50		// take the context too, so the channel send's select can read
    51		// from the Done channel.
    52		AppendClaims(ctx context.Context, dst []camtypes.Claim, permaNode blob.Ref,
    53			signerFilter string,
    54			attrFilter string) ([]camtypes.Claim, error)
    55	
    56		// TODO(bradfitz): methods below this line are slated for a redesign
    57		// to work efficiently for the new in-memory index.
    58	
    59		// dest must be closed, even when returning an error.
    60		// limit <= 0 means unlimited.
    61		GetRecentPermanodes(ctx context.Context, dest chan<- camtypes.RecentPermanode,
    62			owner blob.Ref,
    63			limit int,
    64			before time.Time) error
    65	
    66		// SearchPermanodes finds permanodes matching the provided
    67		// request and sends unique permanode blobrefs to dest.
    68		// In particular, if request.FuzzyMatch is true, a fulltext
    69		// search is performed (if supported by the attribute(s))
    70		// instead of an exact match search.
    71		// If request.Query is blank, the permanodes which have
    72		// request.Attribute as an attribute (regardless of its value)
    73		// are searched.
    74		// Additionally, if request.Attribute is blank, all attributes
    75		// are searched (as fulltext), otherwise the search is
    76		// restricted  to the named attribute.
    77		//
    78		// dest is always closed, regardless of the error return value.
    79		SearchPermanodesWithAttr(ctx context.Context, dest chan<- blob.Ref,
    80			request *camtypes.PermanodeByAttrRequest) error
    81	
    82		// ExistingFileSchemas returns 0 or more blobrefs of "bytes"
    83		// (TODO(bradfitz): or file?) schema blobs that represent the
    84		// bytes of a file given in bytesRef.  The file schema blobs
    85		// returned are not guaranteed to reference chunks that still
    86		// exist on the blobservers, though.  It's purely a hint for
    87		// clients to avoid uploads if possible.  Before re-using any
    88		// returned blobref they should be checked.
    89		//
    90		// Use case: a user drag & drops a large file onto their
    91		// browser to upload.  (imagine that "large" means anything
    92		// larger than a blobserver's max blob size) JavaScript can
    93		// first SHA-1 the large file locally, then send the
    94		// wholeFileRef to this call and see if they'd previously
    95		// uploaded the same file in the past.  If so, the upload
    96		// can be avoided if at least one of the returned schemaRefs
    97		// can be validated (with a validating HEAD request) to still
    98		// all exist on the blob server.
    99		ExistingFileSchemas(wholeFileRef ...blob.Ref) (schemaRefs WholeRefToFile, err error)
   100	
   101		// GetDirMembers sends on dest the children of the static
   102		// directory dirRef. It returns os.ErrNotExist if dirRef
   103		// is nil.
   104		// dest must be closed, even when returning an error.
   105		// limit <= 0 means unlimited.
   106		GetDirMembers(ctx context.Context, dirRef blob.Ref, dest chan<- blob.Ref, limit int) error
   107	
   108		// Given an owner key, a camliType 'claim', 'attribute' name,
   109		// and specific 'value', find the most recent permanode that has
   110		// a corresponding 'set-attribute' claim attached.
   111		// Returns os.ErrNotExist if none is found.
   112		// Only attributes white-listed by IsIndexedAttribute are valid.
   113		// TODO(bradfitz): ErrNotExist here is a weird error message ("file" not found). change.
   114		// TODO(bradfitz): use keyId instead of signer?
   115		PermanodeOfSignerAttrValue(ctx context.Context, signer blob.Ref, attr, val string) (blob.Ref, error)
   116	
   117		// PathsOfSignerTarget queries the index about "camliPath:"
   118		// URL-dispatch attributes.
   119		//
   120		// It returns a list of all the path claims that have been signed
   121		// by the provided signer and point at the given target.
   122		//
   123		// This is used when editing a permanode, to figure work up
   124		// the name resolution tree backwards ultimately to a
   125		// camliRoot permanode (which should know its base URL), and
   126		// then the complete URL(s) of a target can be found.
   127		PathsOfSignerTarget(ctx context.Context, signer, target blob.Ref) ([]*camtypes.Path, error)
   128	
   129		// All Path claims for (signer, base, suffix)
   130		PathsLookup(ctx context.Context, signer, base blob.Ref, suffix string) ([]*camtypes.Path, error)
   131	
   132		// Most recent Path claim for (signer, base, suffix) as of
   133		// provided time 'at', or most recent if 'at' is nil.
   134		PathLookup(ctx context.Context, signer, base blob.Ref, suffix string, at time.Time) (*camtypes.Path, error)
   135	
   136		// EdgesTo finds references to the provided ref.
   137		//
   138		// For instance, if ref is a permanode, it might find the parent permanodes
   139		// that have ref as a member.
   140		// Or, if ref is a static file, it might find static directories which contain
   141		// that file.
   142		// This is a way to go "up" or "back" in a hierarchy.
   143		//
   144		// opts may be nil to accept the defaults.
   145		EdgesTo(ref blob.Ref, opts *camtypes.EdgesToOpts) ([]*camtypes.Edge, error)
   146	
   147		// EnumerateBlobMeta calls fn for each blob known to the
   148		// indexer (which may be a subset of all total blobs, since
   149		// the indexer is typically configured to not see non-metadata
   150		// blobs). The blobs may be sent in any order.  If the context
   151		// finishes, the return error is ctx.Err().
   152		// If the provided function returns false, iteration ends with a nil
   153		// return value.
   154		EnumerateBlobMeta(context.Context, func(camtypes.BlobMeta) bool) error
   155	}