schema

package
v0.0.0-...-f369c56 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 24, 2014 License: Apache-2.0 Imports: 35 Imported by: 0

Documentation

Overview

Package schema manipulates Camlistore schema blobs.

A schema blob is a JSON-encoded blob that describes other blobs. See documentation in Camlistore's doc/schema/ directory.

Index

Constants

View Source 
const MaxSchemaBlobSize = 1 << 20

MaxSchemaBlobSize represents the upper bound for how large a schema blob may be.

View Source 
const ShareHaveRef = "haveref"

ShareHaveRef is the auth type specifying that if you "have the reference" (know the blobref to the haveref share blob), then you have access to the referenced object from that share blob. This is the "send a link to a friend" access model.

Variables

View Source 
var DefaultStatHasher = &defaultStatHasher{}
View Source 
var (
	ErrNoCamliVersion = errors.New("schema: no camliVersion key in map")
)
View Source 
var UnknownLocation = time.FixedZone("Unknown", -60) // 1 minute west

UnknownLocation is a magic timezone value used when the actual location of a time is unknown. For instance, EXIF files commonly have a time without a corresponding location or timezone offset.

Functions

func FileTime 

func FileTime(f io.ReaderAt) (time.Time, error)

FileTime returns the best guess of the file's creation time (or modtime). If the file doesn't have its own metadata indication the creation time (such as in EXIF), FileTime uses the modification time from the file system. It there was a valid EXIF but an error while trying to get a date from it, it logs the error and tries the other methods.

func IsInterestingTitle 

func IsInterestingTitle(title string) bool

IsInterestingTitle returns whether title would be interesting information as a title for a permanode. For example, filenames automatically created by cameras, such as IMG_XXXX.JPG, do not add any interesting value.

func IsMissingField 

func IsMissingField(err error) bool

IsMissingField returns whether error is of type MissingFieldError.

func IsZoneKnown 

func IsZoneKnown(t time.Time) bool

IsZoneKnown reports whether t is in a known timezone. Camlistore uses the magic timezone offset of 1 minute west of UTC to mean that the timezone wasn't known.

func LikelySchemaBlob 

func LikelySchemaBlob(buf []byte) bool

LikelySchemaBlob returns quickly whether buf likely contains (or is the prefix of) a schema blob.

func RFC3339FromTime 

func RFC3339FromTime(t time.Time) string

RFC3339FromTime returns an RFC3339-formatted time.

If the timezone is known, the time will be converted to UTC and returned with a "Z" suffix. For unknown zones, the timezone will be "-00:01" (1 minute west of UTC).

Fractional seconds are only included if the time has fractional seconds.

func WriteFileChunks 

func WriteFileChunks(bs blobserver.StatReceiver, file *Builder, r io.Reader) error

WriteFileChunks uploads chunks of r to bs while populating file. It does not upload file.

func WriteFileFromReader 

func WriteFileFromReader(bs blobserver.StatReceiver, filename string, r io.Reader) (blob.Ref, error)

WriteFileFromReader creates and uploads a "file" JSON schema composed of chunks of r, also uploading the chunks. The returned BlobRef is of the JSON file schema blob. The filename is optional.

func WriteFileMap 

func WriteFileMap(bs blobserver.StatReceiver, file *Builder, r io.Reader) (blob.Ref, error)

WriteFileMap uploads chunks of r to bs while populating file and finally uploading file's Blob. The returned blobref is of file's JSON blob.

Types

type AnyBlob 

type AnyBlob interface {
	Blob() *Blob
}

AnyBlob represents any type of schema blob.

type Blob 

type Blob struct {
	// contains filtered or unexported fields
}

A Blob represents a Camlistore schema blob. It is immutable.

func BlobFromReader 

func BlobFromReader(ref blob.Ref, r io.Reader) (*Blob, error)

BlobReader returns a new Blob from the provided Reader r, which should be the body of the provided blobref. Note: the hash checksum is not verified.

func (*Blob) AsClaim 

func (b *Blob) AsClaim() (c Claim, ok bool)

AsClaim returns a Claim if the receiver Blob has all the required fields.

func (*Blob) AsShare 

func (b *Blob) AsShare() (s Share, ok bool)

AsShare returns a Share if the receiver Blob has all the required fields.

func (*Blob) AsStaticFile 

func (b *Blob) AsStaticFile() (sf StaticFile, ok bool)

AsStaticFile returns the Blob as a StaticFile if it represents one. Otherwise, it returns false in the boolean parameter and the zero value of StaticFile.

func (*Blob) Blob 

func (b *Blob) Blob() *Blob

Blob returns itself, so it satisifies the AnyBlob interface.

func (*Blob) BlobRef 

func (b *Blob) BlobRef() blob.Ref

BlobRef returns the schema blob's blobref.

func (*Blob) Builder 

func (b *Blob) Builder() *Builder

func (*Blob) ByteParts 

func (b *Blob) ByteParts() []BytesPart

ByteParts returns the "parts" field. The caller owns the returned slice.

func (*Blob) ClaimDate 

func (b *Blob) ClaimDate() (time.Time, error)

ClaimDate returns the "claimDate" field. If there is no claimDate, the error will be a MissingFieldError.

func (*Blob) DirectoryEntries 

func (b *Blob) DirectoryEntries() (br blob.Ref, ok bool)

DirectoryEntries the "entries" field if valid and b's type is "directory".

func (*Blob) FileMode 

func (b *Blob) FileMode() os.FileMode

func (*Blob) FileName 

func (b *Blob) FileName() string

FileName returns the file, directory, or symlink's filename, or the empty string. TODO: move this off *Blob to a specialized type.

func (*Blob) JSON 

func (b *Blob) JSON() string

JSON returns the JSON bytes of the schema blob.

func (*Blob) MapGid 

func (b *Blob) MapGid() int

MapGid returns the most appropriate mapping from this file's group to the local machine's group, trying first a match by name, followed by just mapping the number through directly.

func (*Blob) MapUid 

func (b *Blob) MapUid() int

MapUid returns the most appropriate mapping from this file's owner to the local machine's owner, trying first a match by name, followed by just mapping the number through directly.

func (*Blob) ModTime 

func (b *Blob) ModTime() time.Time

ModTime returns the "unixMtime" field, or the zero time.

func (*Blob) NewDirReader 

func (b *Blob) NewDirReader(fetcher blob.Fetcher) (*DirReader, error)

func (*Blob) NewFileReader 

func (b *Blob) NewFileReader(fetcher blob.Fetcher) (*FileReader, error)

func (*Blob) PartsSize 

func (b *Blob) PartsSize() int64

PartsSize returns the number of bytes represented by the "parts" field. TODO: move this off *Blob to a specialized type.

func (*Blob) ShareAuthType 

func (b *Blob) ShareAuthType() string

func (*Blob) ShareTarget 

func (b *Blob) ShareTarget() blob.Ref

func (*Blob) StaticSetMembers 

func (b *Blob) StaticSetMembers() []blob.Ref

func (*Blob) Type 

func (b *Blob) Type() string

Type returns the blob's "camliType" field.

type Buildable 

type Buildable interface {
	Builder() *Builder
}

Buildable returns a Builder from a base.

type Builder 

type Builder struct {
	// contains filtered or unexported fields
}

A Builder builds a JSON blob. After mutating the Builder, call Blob to get the built blob.

func NewAddAttributeClaim 

func NewAddAttributeClaim(permaNode blob.Ref, attr, value string) *Builder

func NewBuilder 

func NewBuilder() *Builder

NewBuilder returns a new blob schema builder. The "camliVersion" field is set to "1" by default and the required "camliType" field is NOT set.

func NewCommonFileMap 

func NewCommonFileMap(fileName string, fi os.FileInfo) *Builder

func NewDelAttributeClaim 

func NewDelAttributeClaim(permaNode blob.Ref, attr, value string) *Builder

NewDelAttributeClaim creates a new claim to remove value from the values set for the attribute attr of permaNode. If value is empty then all the values for attribute are cleared.

func NewDeleteClaim 

func NewDeleteClaim(target blob.Ref) *Builder

NewDeleteClaim creates a new claim to delete a target claim or permanode.

func NewDirMap 

func NewDirMap(fileName string) *Builder

NewDirMap returns a new builder of a type "directory" schema for the provided fileName.

func NewFileMap 

func NewFileMap(fileName string) *Builder

NewFileMap returns a new builder of a type "file" schema for the provided fileName. The chunk parts of the file are not populated.

func NewHashPlannedPermanode 

func NewHashPlannedPermanode(h hash.Hash) *Builder

NewHashPlannedPermanode returns a planned permanode with the sum of the hash, prefixed with "sha1-", as the key.

func NewPlannedPermanode 

func NewPlannedPermanode(key string) *Builder

NewPlannedPermanode returns a permanode with a fixed key. Like NewUnsignedPermanode, this builder is also not yet signed. Callers of NewPlannedPermanode must sign the map with a fixed claimDate and GPG date to create consistent JSON encodings of the Map (its blobref), between runs.

func NewSetAttributeClaim 

func NewSetAttributeClaim(permaNode blob.Ref, attr, value string) *Builder

func NewShareRef 

func NewShareRef(authType string, target blob.Ref, transitive bool) *Builder

NewShareRef creates a *Builder for a "share" claim.

func NewUnsignedPermanode 

func NewUnsignedPermanode() *Builder

NewUnsignedPermanode returns a new random permanode, not yet signed.

func (*Builder) Blob 

func (bb *Builder) Blob() *Blob

Blob builds the Blob. The builder continues to be usable after a call to Build.

func (*Builder) Builder 

func (bb *Builder) Builder() *Builder

Builder returns a clone of itself and satisifies the Buildable interface.

func (*Builder) CapCreationTime 

func (bb *Builder) CapCreationTime() *Builder

CapCreationTime caps the "unixCtime" field to be less or equal than "unixMtime"

func (*Builder) ClaimType 

func (bb *Builder) ClaimType() ClaimType

ClaimType returns the claimType value, or the empty string.

func (*Builder) IsClaimType 

func (bb *Builder) IsClaimType() bool

IsClaimType returns whether this blob builder is for a type which should be signed. (a "claim" or "permanode")

func (*Builder) JSON 

func (bb *Builder) JSON() (string, error)

JSON returns the JSON of the blob as built so far.

func (*Builder) ModTime 

func (bb *Builder) ModTime() (t time.Time, ok bool)

ModTime returns the "unixMtime" modtime field, if set.

func (*Builder) PartsSize 

func (bb *Builder) PartsSize() int64

PartsSize returns the number of bytes represented by the "parts" field.

func (*Builder) PopulateDirectoryMap 

func (bb *Builder) PopulateDirectoryMap(staticSetRef blob.Ref) *Builder

PopulateDirectoryMap sets the type of *Builder to "directory" and sets the "entries" field to the provided staticSet blobref.

func (*Builder) PopulateParts 

func (bb *Builder) PopulateParts(size int64, parts []BytesPart) error

PopulateParts sets the "parts" field of the blob with the provided parts. The sum of the sizes of parts must match the provided size or an error is returned. Also, each BytesPart may only contain either a BytesPart or a BlobRef, but not both.

func (*Builder) SetClaimDate 

func (bb *Builder) SetClaimDate(t time.Time) *Builder

SetClaimDate sets the "claimDate" on a claim. It is a fatal error to call SetClaimDate if the Map isn't of Type "claim".

func (*Builder) SetFileName 

func (bb *Builder) SetFileName(name string) *Builder

SetFileName sets the fileName or fileNameBytes field. The filename is truncated to just the base.

func (*Builder) SetModTime 

func (bb *Builder) SetModTime(t time.Time) *Builder

SetModTime sets the "unixMtime" field.

func (*Builder) SetRawStringField 

func (bb *Builder) SetRawStringField(key, value string) *Builder

SetRawStringField sets a raw string field in the underlying map.

func (*Builder) SetShareExpiration 

func (bb *Builder) SetShareExpiration(t time.Time)

SetShareExpiration sets the expiration time on share claim. It panics if bb isn't a "share" claim type. If t is zero, the expiration is removed.

func (*Builder) SetShareIsTransitive 

func (bb *Builder) SetShareIsTransitive(b bool)

func (*Builder) SetSigner 

func (bb *Builder) SetSigner(signer blob.Ref) *Builder

SetSigner sets the camliSigner field. Calling SetSigner is unnecessary if using Sign.

func (*Builder) SetSymlinkTarget 

func (bb *Builder) SetSymlinkTarget(target string) *Builder

SetSymlinkTarget sets bb to be of type "symlink" and sets the symlink's target.

func (*Builder) SetType 

func (bb *Builder) SetType(t string) *Builder

SetType sets the camliType field.

func (*Builder) Sign 

func (bb *Builder) Sign(signer *Signer) (string, error)

SignAt sets the blob builder's camliSigner field with SetSigner and returns the signed JSON using the provided signer.

func (*Builder) SignAt 

func (bb *Builder) SignAt(signer *Signer, sigTime time.Time) (string, error)

SignAt sets the blob builder's camliSigner field with SetSigner and returns the signed JSON using the provided signer. The provided sigTime is the time of the signature, used mostly for planned permanodes. If the zero value, the current time is used.

func (*Builder) Type 

func (bb *Builder) Type() string

Type returns the camliType value.

type BytesPart 

type BytesPart struct {
	// Size is the number of bytes that this part contributes to the overall segment.
	Size uint64 `json:"size"`

	// At most one of BlobRef or BytesRef must be non-zero
	// (Valid), but it's illegal for both.
	// If neither are set, this BytesPart represents Size zero bytes.
	// BlobRef refers to raw bytes. BytesRef references a "bytes" schema blob.
	BlobRef  blob.Ref `json:"blobRef,omitempty"`
	BytesRef blob.Ref `json:"bytesRef,omitempty"`

	// Offset optionally specifies the offset into BlobRef to skip
	// when reading Size bytes.
	Offset uint64 `json:"offset,omitempty"`
}

BytesPart is the type representing one of the "parts" in a "file" or "bytes" JSON schema.

See doc/schema/bytes.txt and doc/schema/files/file.txt.

type Claim 

type Claim struct {
	// contains filtered or unexported fields
}

A Claim is a Blob that is signed.

func (Claim) Attribute 

func (c Claim) Attribute() string

Attribute returns the "attribute" field, if set.

func (Claim) Blob 

func (c Claim) Blob() *Blob

Blob returns the claim's Blob.

func (Claim) ClaimDateString 

func (c Claim) ClaimDateString() string

ClaimDate returns the blob's "claimDate" field.

func (Claim) ClaimType 

func (c Claim) ClaimType() string

ClaimType returns the blob's "claimType" field.

func (Claim) ModifiedPermanode 

func (c Claim) ModifiedPermanode() blob.Ref

ModifiedPermanode returns the claim's "permaNode" field, if it's a claim that modifies a permanode. Otherwise a zero blob.Ref is returned.

func (Claim) Target 

func (c Claim) Target() blob.Ref

Target returns the blob referenced by the Share if it's a ShareClaim claim, or the object being deleted if it's a DeleteClaim claim. Otherwise a zero blob.Ref is returned.

func (Claim) Value 

func (c Claim) Value() string

Value returns the "value" field, if set.

type ClaimType 

type ClaimType string

ClaimType is one of the valid "claimType" fields in a "claim" schema blob. See doc/schema/claims/. 

const (
	SetAttributeClaim ClaimType = "set-attribute"
	AddAttributeClaim ClaimType = "add-attribute"
	DelAttributeClaim ClaimType = "del-attribute"
	ShareClaim        ClaimType = "share"
	// DeleteClaim deletes a permanode or another claim.
	// A delete claim can itself be deleted, and so on.
	DeleteClaim ClaimType = "delete"
)

type DirReader 

type DirReader struct {
	// contains filtered or unexported fields
}

A DirReader reads the entries of a "directory" schema blob's referenced "static-set" blob.

func NewDirReader 

func NewDirReader(fetcher blob.Fetcher, dirBlobRef blob.Ref) (*DirReader, error)

NewDirReader creates a new directory reader and prepares to fetch the static-set entries

func (*DirReader) Readdir 

func (dr *DirReader) Readdir(n int) (entries []DirectoryEntry, err error)

Readdir implements the Directory interface.

func (*DirReader) StaticSet 

func (dr *DirReader) StaticSet() ([]blob.Ref, error)

StaticSet returns the whole of the static set members of that directory

type Directory 

type Directory interface {
	// Readdir reads the contents of the directory associated with dr
	// and returns an array of up to n DirectoryEntries structures.
	// Subsequent calls on the same file will yield further
	// DirectoryEntries.
	// If n > 0, Readdir returns at most n DirectoryEntry structures. In
	// this case, if Readdir returns an empty slice, it will return
	// a non-nil error explaining why. At the end of a directory,
	// the error is os.EOF.
	// If n <= 0, Readdir returns all the DirectoryEntries from the
	// directory in a single slice. In this case, if Readdir succeeds
	// (reads all the way to the end of the directory), it returns the
	// slice and a nil os.Error. If it encounters an error before the
	// end of the directory, Readdir returns the DirectoryEntry read
	// until that point and a non-nil error.
	Readdir(count int) ([]DirectoryEntry, error)
}

Directory is a read-only interface to a "directory" schema blob.

type DirectoryEntry 

type DirectoryEntry interface {
	// CamliType returns the schema blob's "camliType" field.
	// This may be "file", "directory", "symlink", or other more
	// obscure types added in the future.
	CamliType() string

	FileName() string
	BlobRef() blob.Ref

	File() (File, error)           // if camliType is "file"
	Directory() (Directory, error) // if camliType is "directory"
	Symlink() (Symlink, error)     // if camliType is "symlink"
	FIFO() (FIFO, error)           // if camliType is "fifo"
	Socket() (Socket, error)       // If camliType is "socket"
}

DirectoryEntry is a read-only interface to an entry in a (static) directory.

func NewDirectoryEntryFromBlobRef 

func NewDirectoryEntryFromBlobRef(fetcher blob.Fetcher, blobRef blob.Ref) (DirectoryEntry, error)

NewDirectoryEntryFromBlobRef takes a BlobRef and returns a 

DirectoryEntry if the BlobRef contains a type "file", "directory",
"symlink", "fifo" or "socket".

TODO: ""char", "block", probably. later.

type FIFO 

type FIFO interface {
}

FIFO is the read-only interface to a "fifo" schema blob.

type File 

type File interface {
	io.Closer
	io.ReaderAt
	io.Reader
	Size() int64
}

File is the interface returned when opening a DirectoryEntry that is a regular file.

type FileReader 

type FileReader struct {
	// Immutable stuff:
	*io.SectionReader // provides Read, Seek, and Size.
	// contains filtered or unexported fields
}

A FileReader reads the bytes of "file" and "bytes" schema blobrefs.

func NewFileReader 

func NewFileReader(fetcher blob.Fetcher, fileBlobRef blob.Ref) (*FileReader, error)

NewFileReader returns a new FileReader reading the contents of fileBlobRef, fetching blobs from fetcher. The fileBlobRef must be of a "bytes" or "file" schema blob.

The caller should call Close on the FileReader when done reading.

func (*FileReader) Close 

func (fr *FileReader) Close() error

Close currently does nothing.

func (*FileReader) FileName 

func (fr *FileReader) FileName() string

FileName returns the file schema's filename, if any.

func (*FileReader) GetChunkOffsets 

func (fr *FileReader) GetChunkOffsets(c chan<- int64) error

GetChunkOffsets sends c each of the file's chunk offsets. The offsets are not necessarily sent in order, and all ranges of the file are not necessarily represented if the file contains zero holes. The channel c is closed before the function returns, regardless of error.

func (*FileReader) LoadAllChunks 

func (fr *FileReader) LoadAllChunks()

LoadAllChunks causes all chunks of the file to be loaded as quickly as possible. The contents are immediately discarded, so it is assumed that the fetcher is a caching fetcher.

func (*FileReader) ReadAt 

func (fr *FileReader) ReadAt(p []byte, offset int64) (n int, err error)

func (*FileReader) UnixMtime 

func (fr *FileReader) UnixMtime() time.Time

UnixMtime returns the file schema's UnixMtime field, or the zero value.

type MissingFieldError 

type MissingFieldError string

A MissingFieldError represents a missing JSON field in a schema blob.

func (MissingFieldError) Error 

func (e MissingFieldError) Error() string

type Share 

type Share struct {
	Claim
}

A Share is a claim for giving access to a user's blob(s). When returned from (*Blob).AsShare, it always represents a valid share with all required fields.

func (Share) AuthType 

func (s Share) AuthType() string

AuthType returns the AuthType of the Share.

func (Share) IsExpired 

func (s Share) IsExpired() bool

IsExpired reports whether this share has expired.

func (Share) IsTransitive 

func (s Share) IsTransitive() bool

IsTransitive returns whether the Share transitively gives access to everything reachable from the referenced blob.

type Signer 

type Signer struct {
	// contains filtered or unexported fields
}

A Signer signs the JSON schema blobs that require signing, such as claims and permanodes.

func NewSigner 

func NewSigner(pubKeyRef blob.Ref, armoredPubKey io.Reader, privateKeySource interface{}) (*Signer, error)

NewSigner returns an Signer given an armored public key's blobref, its armored content, and its associated private key entity. The privateKeySource must be either an *openpgp.Entity or a string filename to a secret key.

func (*Signer) SignJSON 

func (s *Signer) SignJSON(json string, t time.Time) (string, error)

SignJSON signs the provided json at the optional time t. If t is the zero Time, the current time is used.

func (*Signer) String 

func (s *Signer) String() string

type Socket 

type Socket interface {
}

Socket is the read-only interface to a "socket" schema blob.

type StatHasher 

type StatHasher interface {
	Lstat(fileName string) (os.FileInfo, error)
	Hash(fileName string) (blob.Ref, error)
}

type StaticFIFO 

type StaticFIFO struct {
	StaticFile
}

A StaticFIFO is a StaticFile that is also a fifo.

type StaticFile 

type StaticFile struct {
	// contains filtered or unexported fields
}

A StaticFile is a Blob representing a file, symlink fifo or socket (or device file, when support for these is added).

func (StaticFile) AsStaticFIFO 

func (sf StaticFile) AsStaticFIFO() (fifo StaticFIFO, ok bool)

AsStaticFIFO returns the StatifFile as a StaticFIFO if the StaticFile represents a fifo. Otherwise, it returns the zero value of StaticFIFO and false.

func (StaticFile) AsStaticSocket 

func (sf StaticFile) AsStaticSocket() (ss StaticSocket, ok bool)

AsSataticSocket returns the StaticFile as a StaticSocket if the StaticFile represents a socket. Otherwise, it returns the zero value of StaticSocket and false. 

func (sf StaticFile) AsStaticSymlink() (s StaticSymlink, ok bool)

AsStaticSymlink returns the StaticFile as a StaticSymlink if the StaticFile represents a symlink. Othwerwise, it retuns the zero value of StaticSymlink and false.

func (StaticFile) FileName 

func (sf StaticFile) FileName() string

FileName returns the StaticFile's FileName if is not the empty string, otherwise it returns its FileNameBytes concatenated into a string.

type StaticSet 

type StaticSet struct {
	// contains filtered or unexported fields
}

func (*StaticSet) Add 

func (ss *StaticSet) Add(ref blob.Ref)

func (*StaticSet) Blob 

func (ss *StaticSet) Blob() *Blob

Map returns a Camli map of camliType "static-set" TODO: delete this method

type StaticSocket 

type StaticSocket struct {
	StaticFile
}

A StaticSocket is a StaticFile that is also a socket. 

type StaticSymlink struct {
	// We name it `StaticSymlink' rather than just `Symlink' since
	// a type called Symlink is already in schema.go.
	StaticFile
}

A StaticSymlink is a StaticFile that is also a symbolic link.

func (StaticSymlink) SymlinkTargetString 

func (sl StaticSymlink) SymlinkTargetString() string

SymlinkTargetString returns the field symlinkTarget if is non-empty. Otherwise it returns the contents of symlinkTargetBytes concatenated as a string. 

type Symlink interface {
}

Source Files

View all Source files

Directories

Path Synopsis
Package nodeattr contains constants for permanode attribute names.
 Package nodeattr contains constants for permanode attribute names.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.