syftsdk

package
v0.8.3 Latest Latest
Warning

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

Go to latest
Published: Jul 30, 2025 License: Apache-2.0 Imports: 27 Imported by: 0

Documentation

Index

Constants

View Source
const (
	AutoDetectWorkers = 0
	DefaultWorkers    = 8
)
View Source
const (
	CodePresignedURLErrors    = "E_PRESIGNED_URL"            // prefix for all presigned url errors
	CodePresignedURLExpired   = "E_PRESIGNED_URL_EXPIRED"    // presigned URL has expired
	CodePresignedURLInvalid   = "E_PRESIGNED_URL_INVALID"    // presigned URL is malformed or invalid
	CodePresignedURLForbidden = "E_PRESIGNED_URL_FORBIDDEN"  // access denied to presigned URL
	CodePresignedURLNotFound  = "E_PRESIGNED_URL_NOT_FOUND"  // object not found via presigned URL
	CodePresignedURLRateLimit = "E_PRESIGNED_URL_RATE_LIMIT" // rate limited by S3
)
View Source
const (
	// Generic request/server errors
	CodeInvalidRequest = "E_INVALID_REQUEST" // bad or invalid request
	CodeRateLimited    = "E_RATE_LIMITED"    // rate limit exceeded
	CodeInternalError  = "E_INTERNAL_ERROR"  // internal server error
	CodeAccessDenied   = "E_ACCESS_DENIED"   // access denied
	CodeUnknownError   = "E_UNKNOWN_ERR"     // unknown error

	// Auth errors
	CodeAuthInvalidCredentials    = "E_AUTH_INVALID_CREDENTIALS"     // authentication credentials (e.g., token) are invalid, expired, or malformed.
	CodeAuthTokenGenerationFailed = "E_AUTH_TOKEN_GENERATION_FAILED" // a failure during the generation of new authentication tokens.
	CodeAuthOTPVerificationFailed = "E_AUTH_OTP_VERIFICATION_FAILED" // Email One-Time Password (OTP) verification failed.
	CodeAuthTokenRefreshFailed    = "E_AUTH_TOKEN_REFRESH_FAILED"    // a failure during the attempt to refresh an authentication token.
	CodeAuthNotificationFailed    = "E_AUTH_NOTIFICATION_FAILED"     // a failure in sending an authentication-related notification (e.g., OTP email/SMS).

	// Datasite errors
	CodeDatasiteNotFound    = "E_DATASITE_NOT_FOUND"    // the specified datasite resource could not be found.
	CodeDatasiteInvalidPath = "E_DATASITE_INVALID_PATH" // the provided path for a datasite resource is invalid or malformed.

	// Blob errors
	CodeBlobNotFound     = "E_BLOB_NOT_FOUND"               // the specified blob could not be found.
	CodeBlobListFailed   = "E_BLOB_LIST_OPERATION_FAILED"   // a failure during the operation to list blobs.
	CodeBlobPutFailed    = "E_BLOB_PUT_OPERATION_FAILED"    // a failure during the operation to upload/put a blob.
	CodeBlobGetFailed    = "E_BLOB_GET_OPERATION_FAILED"    // a failure during the operation to download/get a blob.
	CodeBlobDeleteFailed = "E_BLOB_DELETE_OPERATION_FAILED" // a failure during the operation to delete a blob.

	// ACL errors
	CodeACLUpdateFailed = "E_ACL_UPDATE_FAILED" // a failure during the operation to update an ACL.
)
View Source
const (
	HeaderUserAgent    = "User-Agent"
	HeaderSyftVersion  = "X-Syft-Version"
	HeaderSyftUser     = "X-Syft-User"
	HeaderSyftDeviceId = "X-Syft-Device-Id"
)
View Source
const (
	DefaultBaseURL = "https://syftbox.net"
)
View Source
const (
	TokenRefreshInterval = 24 * time.Hour
)

Variables

View Source
var (
	// ErrEventsNotConnected is returned when trying to use events without an active connection
	ErrEventsNotConnected = errors.New("sdk: events: not connected")
	// ErrEventsMessageQueueFull is returned when the message queue is full
	ErrEventsMessageQueueFull = errors.New("sdk: events: message queue full")
)
View Source
var (
	// sdk common
	ErrNoRefreshToken = errors.New("sdk: refresh token missing")
	ErrNoServerURL    = errors.New("sdk: server url missing")
	ErrInvalidEmail   = errors.New("sdk: invalid email")

	// auth
	ErrInvalidOTP = errors.New("sdk: invalid otp")

	// blob
	ErrNoPermissions = errors.New("sdk: no permissions")
	ErrFileNotFound  = errors.New("sdk: file not found")
)
View Source
var HTTPClient = req.C().
	SetCommonRetryCount(3).
	SetCommonRetryFixedInterval(1*time.Second).
	SetUserAgent(SyftBoxUserAgent).
	SetCommonHeader(HeaderSyftVersion, version.Version).
	SetCommonHeader(HeaderSyftDeviceId, utils.HWID).
	SetJsonMarshal(jsonMarshal).
	SetJsonUnmarshal(jsonUmarshal)

A simple HTTP client with some common values set

View Source
var SyftBoxUserAgent = fmt.Sprintf("SyftBox/%s (%s; %s; %s)", version.Version, version.Revision, runtime.GOOS, runtime.GOARCH)

Functions

func DownloadFile added in v0.7.0

func DownloadFile(ctx context.Context, job *DownloadJob) (string, error)

DownloadFile downloads a single file from the provided URL to the temp directory Returns the path to the downloaded file or an error

func Downloader

func Downloader(ctx context.Context, opts *DownloadOpts) <-chan *DownloadResult

func IsValidOTP

func IsValidOTP(otp string) bool

func RequestEmailCode added in v0.7.0

func RequestEmailCode(ctx context.Context, serverURL string, email string) error

RequestEmailCode starts the Email verification flow by requesting a one-time password (OTP) from the server.

func UploadPresigned

func UploadPresigned(ctx context.Context, url string, path string, callback ProgressCallback) (*http.Response, error)

Upload a file to a presigned url

Types

type APIError added in v0.7.0

type APIError struct {
	BaseError
}

APIError represents SyftBox API errors

func NewAPIError added in v0.8.0

func NewAPIError(code, message string) *APIError

func (*APIError) Error added in v0.7.0

func (e *APIError) Error() string

type AuthClaims

type AuthClaims struct {
	Type AuthTokenType `json:"type"`
	jwt.RegisteredClaims
}

func ParseToken added in v0.7.0

func ParseToken(token string, tokenType AuthTokenType) (*AuthClaims, error)

func (*AuthClaims) Validate

func (c *AuthClaims) Validate(email string, issuer string) error

type AuthTokenResponse

type AuthTokenResponse struct {
	AccessToken  string `json:"accessToken"`
	RefreshToken string `json:"refreshToken"`
}

func RefreshAuthTokens

func RefreshAuthTokens(ctx context.Context, serverURL string, refreshToken string) (apiResp *AuthTokenResponse, err error)

func VerifyEmailCode

func VerifyEmailCode(ctx context.Context, serverURL string, codeReq *VerifyEmailCodeRequest) (apiResp *AuthTokenResponse, err error)

type AuthTokenType

type AuthTokenType string
const (
	AccessToken  AuthTokenType = "access"
	RefreshToken AuthTokenType = "refresh"
)

type BaseError added in v0.8.0

type BaseError struct {
	Code    string `json:"code"`
	Message string `json:"error"`
}

BaseError provides common error functionality

func (*BaseError) ErrorCode added in v0.8.0

func (e *BaseError) ErrorCode() string

func (*BaseError) ErrorMessage added in v0.8.0

func (e *BaseError) ErrorMessage() string

type BlobAPI

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

func (*BlobAPI) Delete

func (b *BlobAPI) Delete(ctx context.Context, params *DeleteParams) (apiResp *DeleteResponse, err error)

Delete deletes multiple blobs

func (*BlobAPI) Download added in v0.7.0

func (b *BlobAPI) Download(ctx context.Context, params *PresignedParams) (apiResp *PresignedResponse, err error)

Download gets presigned URLs for downloading multiple blobs

func (*BlobAPI) Upload

func (b *BlobAPI) Upload(ctx context.Context, params *UploadParams) (apiResp *UploadResponse, err error)

Upload uploads a file to the blob storage

func (*BlobAPI) UploadPresigned

func (b *BlobAPI) UploadPresigned(ctx context.Context, params *PresignedParams) (apiResp *PresignedResponse, err error)

UploadPresigned gets presigned URLs for uploading multiple blobs

type BlobError

type BlobError struct {
	APIError
	Key string `json:"key"`
}

BlobError represents an error for a specific blob operation

type BlobInfo

type BlobInfo struct {
	Key          string    `json:"key"`
	ETag         string    `json:"etag"`
	Size         int       `json:"size"`
	LastModified time.Time `json:"lastModified"`
}

BlobInfo represents information about a blob

type BlobURL added in v0.7.0

type BlobURL struct {
	Key string `json:"key"`
	URL string `json:"url"`
}

BlobURL represents a presigned URL for a blob

type DatasiteAPI

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

func (*DatasiteAPI) GetView

func (d *DatasiteAPI) GetView(ctx context.Context, params *DatasiteViewParams) (resp *DatasiteViewResponse, err error)

type DatasiteViewParams

type DatasiteViewParams struct{}

DataSiteViewInput represents the input parameters for the datasite view API for now, no params are needed

type DatasiteViewResponse

type DatasiteViewResponse struct {
	Files []BlobInfo `json:"files"`
}

DataSiteViewOutput represents the output from the datasite view API

type DeleteParams

type DeleteParams struct {
	Keys []string `json:"keys"`
}

DeleteParams represents the parameters for deleting blobs

type DeleteResponse

type DeleteResponse struct {
	Deleted []string     `json:"deleted"`
	Errors  []*BlobError `json:"errors"`
}

DeleteResponse represents the response from a blob delete operation

type DownloadFileParams

type DownloadFileParams struct {
	User string   `json:"user"`
	Keys []string `json:"keys"`
}

DownloadFileParams represents the parameters for downloading files

type DownloadFileResponse

type DownloadFileResponse struct {
	URLs   []*BlobURL   `json:"urls"`
	Errors []*BlobError `json:"errors"`
}

DownloadFileResponse represents the response from a file download request

type DownloadJob

type DownloadJob struct {
	URL       string // url to download from
	TargetDir string // directory to save the file to
	Name      string // name to save the file as
	Callback  func(job *DownloadJob, downloadedBytes int64, totalBytes int64)
}

type DownloadOpts added in v0.7.0

type DownloadOpts struct {
	Workers int
	Jobs    []*DownloadJob
}

type DownloadResult

type DownloadResult struct {
	DownloadJob
	DownloadPath string
	Error        error
}

type EventMessage

type EventMessage struct {
	// The message payload
	Message *syftmsg.Message
}

EventMessage represents a message sent or received via the events system

type EventsAPI

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

EventsAPI manages real-time event communication

func (*EventsAPI) Close

func (e *EventsAPI) Close()

Close terminates the WebSocket connection and cleans up

func (*EventsAPI) Connect

func (e *EventsAPI) Connect(ctx context.Context) error

Connect initiates a WebSocket connection

func (*EventsAPI) Get

func (e *EventsAPI) Get() <-chan *syftmsg.Message

Get returns a channel for receiving WebSocket messages

func (*EventsAPI) IsConnected

func (e *EventsAPI) IsConnected() bool

IsConnected returns the current connection status

func (*EventsAPI) Send

func (e *EventsAPI) Send(msg *syftmsg.Message) error

Send sends a message through the WebSocket

type PresignedParams

type PresignedParams struct {
	Keys []string `json:"keys"`
}

PresignedParams represents the parameters for getting presigned URLs

type PresignedResponse

type PresignedResponse struct {
	URLs   []*BlobURL   `json:"urls"`
	Errors []*BlobError `json:"errors"`
}

PresignedResponse represents the response from a presigned URL request

type PresignedURLError added in v0.8.0

type PresignedURLError struct {
	BaseError
}

PresignedURLError represents presigned URL specific errors

func NewPresignedURLError added in v0.8.0

func NewPresignedURLError(code, message string) *PresignedURLError

func (*PresignedURLError) Error added in v0.8.0

func (e *PresignedURLError) Error() string

type ProgressCallback

type ProgressCallback func(uploaded int64, total int64)

type RefreshTokenRequest

type RefreshTokenRequest struct {
	RefreshToken string `json:"refreshToken"`
}

type SDKError added in v0.7.0

type SDKError interface {
	error
	ErrorCode() string
	ErrorMessage() string
}

type SyftSDK

type SyftSDK struct {
	Datasite *DatasiteAPI
	Blob     *BlobAPI
	Events   *EventsAPI
	// contains filtered or unexported fields
}

SyftSDK is the main client for interacting with the Syft API

func New

func New(config *SyftSDKConfig) (*SyftSDK, error)

New creates a new SyftSDK client

func (*SyftSDK) Authenticate

func (s *SyftSDK) Authenticate(ctx context.Context) error

Authenticate sets the user authentication for API calls and events

func (*SyftSDK) Close

func (s *SyftSDK) Close()

Close terminates all connections and cleans up resources

func (*SyftSDK) OnAuthTokenUpdate

func (s *SyftSDK) OnAuthTokenUpdate(fn func(refreshToken string))

type SyftSDKConfig

type SyftSDKConfig struct {
	BaseURL      string // BaseURL is required
	Email        string // Email is required
	RefreshToken string // RefreshToken is required
	AccessToken  string // AccessToken is optional
}

SyftSDKConfig is the configuration for the SyftSDK

func (*SyftSDKConfig) Validate

func (c *SyftSDKConfig) Validate() error

type UploadParams

type UploadParams struct {
	Key               string
	FilePath          string
	ChecksumCRC64NVME string
	Callback          func(uploadedBytes int64, totalBytes int64)
}

UploadParams represents the parameters for uploading a blob

type UploadResponse

type UploadResponse struct {
	Key          string `json:"key"`
	Version      string `json:"version"`
	ETag         string `json:"etag"`
	Size         int64  `json:"size"`
	LastModified string `json:"lastModified"`
}

UploadResponse represents the response from a blob upload

type VerifyEmailCodeRequest

type VerifyEmailCodeRequest struct {
	Email string `json:"email"`
	Code  string `json:"code"`
}

type VerifyEmailRequest

type VerifyEmailRequest struct {
	Email string `json:"email"`
}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL