textile

README

Textile Wrappers

This package contains wrappers around Textile Threads and Buckets.

Usage

Initialization and Startup

Initialize Space's Textile Client by runing

client := textile.NewClient(store)
client.Start(ctx, config)

This will start the Textile connection, try to authenticate to the Hub, create a thread for metadata and a default bucket if there's none.

TODO

• Separate the initialization logic into a new function that can be called from an imported "wallet". That way the initialized metadata and initial buckets can be pulled from the Hub if they exist.

Internal State

Textile Client holds the following objects:

• store: A connection to the store. Used to fetch keys and store the meta thread threadID.
• threads: A connection to Textile's Thread Client, initiated after startup.
• bucketsClient: A connection to Textile's Bucket Client, initiated after startup.
• netc: Wraps Textile network operations.
• isRunning: Boolean that is set to true if the initialization after calling Start finished successfully.
• Ready: A channel that gets emitted to after startup.
• cfg: A reference to the config object.
• isConnectedToHub: A boolean indicating if the initial Hub connection and authorization succeeded. If false, bucket operations will not be replicated on the Hub.

After initialization, Textile Client's state is mainly stored in the "meta thread". This meta thread stores a collection of the buckets the user has created or joined. This meta thread can be synced and joined in case the user wants to go cross-platform. The thread ID of the meta thread is stored in the local store. Operations over the meta thread are done in collections.go.

Creating and joining buckets (bucket_factory.go) adds a bucket instance to the meta thread. Listing and getting buckets query the meta thread to obtain the bucket's threadID and name. Using this info, these methods instantiate a Bucket object (./bucket/bucket.go), which exposes methods to do in bucket operations such as listing and adding files to a bucket.

Hub authentication

Currently, we attempt to connect to the Hub on initialization. In coming releases, we might switch that so that it can be toggled on and off from the API. If the Hub connection succeeds, all bucket operations will include the auth token in the calls to Textile's bucket client. This will trigger Hub replication. The auth token is obtained by signing a challenge received from the Hub using the user private key. If the challenge is signed correctly, the Hub returns a non-expiring auth token that we store so that we don't need to re-authenticate.

The logic for authenticating and prepending the keys before bucket operations can be seen in bucket_factory.go in the method getBucketContext. It creates a Context instance that includes all the necessary information for accessing the correct thread and include the correct auth token.

Documentation

Index

• Constants
• Variables
• func GetDefaultBucketSlug() string
• func GetDefaultMirrorBucketSlug() string
• func NewClient(store db.Store, kc keychain.Keychain, hubAuth hub.HubAuth, uc UsersClient, ...) *textileClient
• func NewListener(client Client, bucketSlug string, handlers []EventHandler) *listener
• func NotFound(slug string) error
• type Buckd
• type Bucket
• type BucketRoot
• type Client
• type EventHandler
• type GetBucketForRemoteFileInput
• type GrpcMailboxNotifier
• type Listener
• type Mailbox
• type SecureBucketClient
  • func NewSecureBucketsClient(client *bucketsClient.Client, kc keychain.Keychain, st store.Store, ...) *SecureBucketClient
  • func (s *SecureBucketClient) ListIpfsPath(ctx context.Context, pth path.Path) (*bucketspb.ListIpfsPathResponse, error)
  • func (s *SecureBucketClient) ListPath(ctx context.Context, key, path string) (*bucketspb.ListPathResponse, error)
  • func (s *SecureBucketClient) PullPath(ctx context.Context, key, path string, writer io.Writer, opts ...bc.Option) error
  • func (s *SecureBucketClient) PullPathAccessRoles(ctx context.Context, key, path string) (map[string]buckets.Role, error)
  • func (s *SecureBucketClient) PushPath(ctx context.Context, key, path string, reader io.Reader, opts ...bc.Option) (result path.Resolved, root path.Resolved, err error)
  • func (s *SecureBucketClient) PushPathAccessRoles(ctx context.Context, key, path string, roles map[string]buckets.Role) error
  • func (s *SecureBucketClient) RemovePath(ctx context.Context, key, path string, opts ...bc.Option) (path.Resolved, error)
• type TextileBuckd
  • func NewBuckd(cfg config.Config) *TextileBuckd
  • func (tb *TextileBuckd) Shutdown() error
  • func (tb *TextileBuckd) Start(ctx context.Context) error
  • func (tb *TextileBuckd) Stop() error
  • func (tb *TextileBuckd) WaitForReady() chan bool
• type UsersClient
  • func CreateUserClient(host string) UsersClient

Constants

const FileCachePrefix = "file_cache"

Variables

var HealthcheckMaxRetriesReachedErr = errors.New(fmt.Sprintf("textile client not initialized after %d attempts", healthcheckFailuresBeforeUnhealthy))

var IpfsAddr string

var MaxThreadsConn int

var MinThreadsConn int

var MongoHost string

var MongoPw string

var MongoRepSet string

var MongoUsr string

Functions

func GetDefaultBucketSlug

func GetDefaultBucketSlug() string

func GetDefaultMirrorBucketSlug

func GetDefaultMirrorBucketSlug() string

func NewClient

func NewClient(
	store db.Store,
	kc keychain.Keychain,
	hubAuth hub.HubAuth,
	uc UsersClient,
	mb Mailbox,
	search search.FilesSearchEngine,
) *textileClient

Creates a new Textile Client

func NewListener

func NewListener(client Client, bucketSlug string, handlers []EventHandler) *listener

func NotFound

func NotFound(slug string) error

Types

type Buckd

type Buckd interface {
	Stop() error
	Start(ctx context.Context) error
}

type Bucket

type Bucket interface {
	bucket.BucketInterface
}

type BucketRoot

type BucketRoot buckets_pb.Root

type Client

type Client interface {
	IsRunning() bool
	IsInitialized() bool
	IsHealthy() bool
	GetDefaultBucket(ctx context.Context) (Bucket, error)
	GetBucket(ctx context.Context, slug string, remoteFile *GetBucketForRemoteFileInput) (Bucket, error)
	GetThreadsConnection() (*threadsClient.Client, error)
	GetModel() model.Model
	ListBuckets(ctx context.Context) ([]Bucket, error)
	ShareBucket(ctx context.Context, bucketSlug string) (*db.Info, error)
	JoinBucket(ctx context.Context, slug string, ti *domain.ThreadInfo) (bool, error)
	CreateBucket(ctx context.Context, bucketSlug string) (Bucket, error)
	ToggleBucketBackup(ctx context.Context, bucketSlug string, bucketBackup bool) (bool, error)
	BucketBackupRestore(ctx context.Context, bucketSlug string) error
	SendMessage(ctx context.Context, recipient crypto.PubKey, body []byte) (*client.Message, error)
	Shutdown() error
	WaitForReady() chan bool
	WaitForHealthy() chan error
	WaitForInitialized() chan bool
	Start(ctx context.Context, cfg config.Config) error
	GetMailAsNotifications(ctx context.Context, seek string, limit int) ([]*domain.Notification, error)
	ShareFilesViaPublicKey(ctx context.Context, paths []domain.FullPath, pubkeys []crypto.PubKey, keys [][]byte) error
	AcceptSharedFilesInvitation(ctx context.Context, invitation domain.Invitation) (domain.Invitation, error)
	RejectSharedFilesInvitation(ctx context.Context, invitation domain.Invitation) (domain.Invitation, error)
	AcceptSharedFileLink(
		ctx context.Context,
		cidHash, password, filename, fileSize string,
	) (*domain.SharedDirEntry, error)
	RemoveKeys(ctx context.Context) error
	AttachMailboxNotifier(notif GrpcMailboxNotifier)
	AttachSynchronizerNotifier(notif sync.EventNotifier)
	GetReceivedFiles(ctx context.Context, accepted bool, seek string, limit int) ([]*domain.SharedDirEntry, string, error)
	GetPublicReceivedFile(ctx context.Context, cidHash string, accepted bool) (*domain.SharedDirEntry, string, error)
	GetSentFiles(ctx context.Context, seek string, limit int) ([]*domain.SharedDirEntry, string, error)
	GetPathAccessRoles(ctx context.Context, b Bucket, path string) ([]domain.Member, error)
	GetPublicShareBucket(ctx context.Context) (Bucket, error)
	DownloadPublicGatewayItem(ctx context.Context, cid cid.Cid) (io.ReadCloser, error)
	GetFailedHealthchecks() int
	DeleteAccount(ctx context.Context) error
	Listen(ctx context.Context, dbID, threadName string) (<-chan threadsClient.ListenEvent, error)
	RestoreDB(ctx context.Context) error
	DisableSync()
}

type EventHandler

type EventHandler interface {
	OnCreate(bucketData *bucket.BucketData, listenEvent *tc.ListenEvent)
	OnRemove(bucketData *bucket.BucketData, listenEvent *tc.ListenEvent)
	OnSave(bucketData *bucket.BucketData, listenEvent *tc.ListenEvent)
}

EventHandler

type GetBucketForRemoteFileInput

type GetBucketForRemoteFileInput struct {
	Path   string
	DbID   string
	Bucket string
}

type GrpcMailboxNotifier

type GrpcMailboxNotifier interface {
	SendNotificationEvent(notif *domain.Notification)
}

type Listener

type Listener interface {
	Listen(context.Context) error
	Close()
}

type Mailbox

type Mailbox interface {
	ListInboxMessages(ctx context.Context, opts ...client.ListOption) ([]client.Message, error)
	SendMessage(ctx context.Context, to thread.PubKey, body []byte) (msg client.Message, err error)
	WatchInbox(ctx context.Context, mevents chan<- mail.MailboxEvent, offline bool) (<-chan cmd.WatchState, error)
	Identity() thread.Identity
}

type SecureBucketClient

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

SecureBucketClient implements the BucketsClient Interface It encrypts data being pushed to the underlying textile client and also decrypts response from the underlying textile client

func NewSecureBucketsClient

func NewSecureBucketsClient(
	client *bucketsClient.Client,
	kc keychain.Keychain,
	st store.Store,
	threads *threadsClient.Client,
	ipfsClient iface.CoreAPI,
	isRemote bool,
) *SecureBucketClient

func (*SecureBucketClient) ListIpfsPath

func (s *SecureBucketClient) ListIpfsPath(ctx context.Context, pth path.Path) (*bucketspb.ListIpfsPathResponse, error)

func (*SecureBucketClient) ListPath

func (s *SecureBucketClient) ListPath(ctx context.Context, key, path string) (*bucketspb.ListPathResponse, error)

func (*SecureBucketClient) PullPath

func (s *SecureBucketClient) PullPath(ctx context.Context, key, path string, writer io.Writer, opts ...bc.Option) error

func (*SecureBucketClient) PullPathAccessRoles

func (s *SecureBucketClient) PullPathAccessRoles(ctx context.Context, key, path string) (map[string]buckets.Role, error)

func (*SecureBucketClient) PushPath

func (s *SecureBucketClient) PushPath(ctx context.Context, key, path string, reader io.Reader, opts ...bc.Option) (result path.Resolved, root path.Resolved, err error)

func (*SecureBucketClient) PushPathAccessRoles

func (s *SecureBucketClient) PushPathAccessRoles(ctx context.Context, key, path string, roles map[string]buckets.Role) error

func (*SecureBucketClient) RemovePath

func (s *SecureBucketClient) RemovePath(ctx context.Context, key, path string, opts ...bc.Option) (path.Resolved, error)

type TextileBuckd

type TextileBuckd struct {
	IsRunning bool
	Ready     chan bool
	// contains filtered or unexported fields
}

func NewBuckd

func NewBuckd(cfg config.Config) *TextileBuckd

func (*TextileBuckd) Shutdown

func (tb *TextileBuckd) Shutdown() error

func (*TextileBuckd) Start

func (tb *TextileBuckd) Start(ctx context.Context) error

func (*TextileBuckd) Stop

func (tb *TextileBuckd) Stop() error

func (*TextileBuckd) WaitForReady

func (tb *TextileBuckd) WaitForReady() chan bool

type UsersClient

type UsersClient interface {
	ListInboxMessages(ctx context.Context, opts ...client.ListOption) ([]client.Message, error)
	SendMessage(ctx context.Context, from thread.Identity, to thread.PubKey, body []byte) (msg client.Message, err error)
	SetupMailbox(ctx context.Context) (mailbox thread.ID, err error)
}

func CreateUserClient

func CreateUserClient(host string) UsersClient