cells_sdk

README

Cells SDK Go (v5)

WARNING: the v5 branch of the SDK is not yet stable and ready: API will still change before the GA release. We yet start to publish some snapshot versions to prepare adaptation of the various clients. Note also that the cells-sdk-go specific API (mainly package v5/transport) is still being refined and some methods will need migration between v4 and v5.

Go SDK for communicating with a Pydio Cells Server.

This library allows fast implementation of clients using the Go language.

It provides:

• an automatically generated API client using go-swagger
• a transport layer that handles authentication and wraps AWS SDK for file transfers
• a bunch of basic examples that use this SDK to perform simple actions on a running Cells server instance

To use this SDK, your server should be running Pydio Cells 4.x or later. For more information, please visit our developer guide.

Usage

The library is publicly available, simply:

go get github.com/pydio/cells-sdk-go/v5 

and import necessary sub-packages in your code.

The transport package provides utilitary methods to ease the set up of a communication with your target Cells instance. You might find the commands that are in the example package useful to jump in.

You can also have a look at the Cells client repository to see more working examples.

Migrate from older versions

From SDK v4

For the v5, we switched to the v2 of the AWS SDK for Go that we use under the hood to transfer files.

If you are relying of some of the class defined in the pydio/cells-sdk-go/v5/transport package, you will have to update your code. You can have a look at the wget and list-bucket commands of the pydio/cells-sdk-go/v5/example package to see sample code and refer to the official AWS documentation to get more help.

From SDK v3

Between version 3 and 4, we have updated the go-swagger version that we use, to v0.30.3 and then to v0.30.5, this should have no impact on your client code.

We have also changed the name of the swagger spec file in Cells that is now: cellsapi-rest.swagger.json.

From SDK v2

Between version 2 and 3, we have updated the go-swagger version that we use, to v0.28.0, this has led to a few breaking changes: you might have to adapt your client code.

We have also reworked our error model in the JSON file: well-known HTTP status are now correctly handled and messages clearer.

Here is a short list of the modification you might have to do in your old code:

• client.PydioCellsRest is now client.PydioCellsRestAPI
• enum objects are managed more cleanly:
  • you have to dereference the pointer to make comparison: *node.Type == models.TreeNodeTypeCOLLECTION
  • you cannot use a string to create a parameter. This won't compile: Type: "COLLECTION" and you must rather write: Type: models.NewTreeNodeType(models.TreeNodeTypeCOLLECTION)
• Acls param in struc models.RestCell has been renamed ACLs

Versioning policy

Between version 2.2 and 3.99 of the Cells server, as the API was still moving and even if we tried to stay backward compatible, we released a minor version of the SDK for each minor version of the Pydio Cells Server: if you are stuck with some servers in v2 or v3, you might still want to use a SDK that has same major.minor version to communicate with your server.

Since the v4, you can use the latest version of the SDK to communicate with any Cells V4+ server.

License

This library is licensed under Apache v2.0 license.

Documentation

Overview

Package cells_sdk provides a ready to use SDK to use the Cells REST API in Go language. It also provides some patterns that ease implementation of Go programs that use the SDK.

Index

• Constants
• type AwsConfigOption
• type ConfigRefresher
• type ConfigRefresherConsumer
• type CredentialProviderOption
• type HttpClientOption
• type RoundTripOption
• type S3Config
  • func NewS3Config() *S3Config
• type SdkConfig
  • func (s *SdkConfig) Expired() bool
  • func (s *SdkConfig) ExpiresAt() time.Time
  • func (s *SdkConfig) GetId() string
  • func (s *SdkConfig) Retrieve(_ context.Context) (string, error)
• type TokenProvider
• type TransportOption

Constants

const (
	CellsApiResourcePath = "/a"
	UserAgentKey         = "User-Agent"
)

Cells constants

const (
	// AuthTypePat relies on a Personal Access Token generated on the server for a given user.
	AuthTypePat = "pat"
	// AuthTypeClientAuth is the legacy authentication method, based on user password: this is less secured.
	AuthTypeClientAuth = "session"
	// AuthTypeOAuth uses OAuth2 credential retrieval flow.
	AuthTypeOAuth = "oauth2"
)

Supported Authentication types for v5+

const (
	DefaultS3Region    = "us-east-1"
	DefaultS3Bucket    = "io"
	DefaultS3ApiSecret = "gatewaysecret"
)

Default S3 parameters

Types

type AwsConfigOption

type AwsConfigOption func(aws.Config) aws.Config

type ConfigRefresher

type ConfigRefresher interface {
	RefreshIfRequired(context.Context, *SdkConfig) (bool, error)
}

type ConfigRefresherConsumer

type ConfigRefresherConsumer interface {
	SetConfigRefresher(ConfigRefresher)
}

type CredentialProviderOption

type CredentialProviderOption func(aws.CredentialsProvider) aws.CredentialsProvider

type HttpClientOption

type HttpClientOption func(*http.Client) *http.Client

type RoundTripOption

type RoundTripOption func(http.RoundTripper) http.RoundTripper

type S3Config

type S3Config struct {
	// Endpoint overrides the default URL generated by the S3 SDK from the bucket name.
	Endpoint string `json:"enpoint"`
	// Region param, usually us-east-1.
	Region string `json:"region"`
	// ApiKey is used by the Cells SDK to transmit the JWT token.
	ApiKey string `json:"apiKey"`
	// ApiSecret identifies this client.
	ApiSecret string `json:"apiSecret"`
	// Bucket name, usually io.
	Bucket string `json:"bucket"`

	// RequestTimout overrides default HTTP request timeout when transfering files.
	RequestTimout int `json:"requestTimout,omitempty"`

	// Legacy
	// Set to true to rather use legacy mode (JWT Auth is transmitted via custom 'X-Pydio-Bearer' header).
	UsePydioSpecificHeader bool `json:"usePydioSpecificHeader"`
	// IsDebug is a convenience legacy flag to add some logging to this S3 client.
	// Should be cleaned as soon as we defined the logging strategy for this repo.
	IsDebug bool `json:"isDebug"`
}

S3Config stores connection parameters to a running Cells instance S3 gateway via the AWS SDK for Go.

func NewS3Config

func NewS3Config() *S3Config

type SdkConfig

type SdkConfig struct {

	// Auth type is a convenience flag to store the type of authentication used by this SDK config
	// in v5, we support: PAT (Personal Access Token), OAuth2 (based on a JWT retrieved interactively via OAuth credential flow) and Basic (login/password, less secured)
	AuthType string `json:"authType,omitempty"`

	// Url stores domain name or IP & port to the server.
	Url string `json:"url"`
	// Username (login) for the currently configured Pydio Account
	User string `json:"user"`

	// IdToken might be a personal access Token (generated on your server) or an OAuth2 Token retrieved via the OIDC code flow.
	IdToken string `json:"idToken,omitempty"`

	// OIDC Code Flow additional info
	// RefreshToken holds the token to refresh your JWT. Warning: this token can be used only **once**, it is then blocked on the server side.
	RefreshToken string `json:"refreshToken,omitempty"`
	// TokenExpiresAt holds the expiration timestamp for the current JWT.
	TokenExpiresAt int `json:"tokenExpiresAt,omitempty"`

	// Password for client credential authentication (Legacy, less secure).
	Password string `json:"password,omitempty"`

	// SkipVerify tells the transport to ignore expired or self-signed TLS certificates.
	SkipVerify bool `json:"skipVerify"`

	// UseTokenCache flags if we should rely on a local cache to avoid retrieving a new JWT token at each request.
	// It is useful to *not* use the cache when running connection tests for instance.
	UseTokenCache bool `json:"useTokenCache"`

	// CustomHeaders holds an optional list of headers to be overridden in requests, e.g. the User-Agent.
	CustomHeaders map[string]string
}

SdkConfig stores parameters to talk to a running Cells instance REST API via the Go SDK.

func (*SdkConfig) Expired

func (s *SdkConfig) Expired() bool

Expired checks if expiration time is in less than 10 seconds or already passed.

func (*SdkConfig) ExpiresAt

func (s *SdkConfig) ExpiresAt() time.Time

func (*SdkConfig) GetId

func (s *SdkConfig) GetId() string

func (*SdkConfig) Retrieve

func (s *SdkConfig) Retrieve(_ context.Context) (string, error)

Retrieve simply returns the ID token that is currently held in the conf.

type TokenProvider

type TokenProvider interface {
	Retrieve(context.Context) (string, error)
	Expired() bool
	ExpiresAt() time.Time
}

type TransportOption

type TransportOption func(*http.Transport) *http.Transport