resource

Documentation

Index

• Constants
• Variables
• type DownloadError
  • func (e *DownloadError) Error() string
  • func (e *DownloadError) Unwrap() error
• type HandlerFuncs
  • func (h HandlerFuncs) Open(ctx context.Context, id Identifier) (*Stream, error)
  • func (h HandlerFuncs) Upload(ctx context.Context, in UploadInput) (Identifier, error)
• type Identifier
  • func Parse(raw string) (Identifier, error)
• type Manager
  • func NewManager(opts ...Option) *Manager
  • func (m *Manager) Download(ctx context.Context, raw string, dstPath string) error
  • func (m *Manager) Open(ctx context.Context, raw string) (*Stream, error)
  • func (m *Manager) Register(scheme string, handler ResourceHandler) error
  • func (m *Manager) Upload(ctx context.Context, scheme string, in UploadInput) (Identifier, error)
• type OpenError
  • func (e *OpenError) Error() string
  • func (e *OpenError) Unwrap() error
• type Option
  • func WithDataMaxBytes(maxBytes int64) Option
  • func WithHTTPClient(client *http.Client) Option
  • func WithHTTPEnabled(enabled bool) Option
  • func WithMaxBytes(maxBytes int64) Option
  • func WithRedirectLimit(limit int) Option
  • func WithRetry(attempts int, baseDelay time.Duration, maxDelay time.Duration) Option
  • func WithTimeoutQuota(timeout time.Duration) Option
• type Options
• type ParseError
  • func (e *ParseError) Error() string
  • func (e *ParseError) Unwrap() error
• type ResourceHandler
• type Stream
• type UploadError
  • func (e *UploadError) Error() string
  • func (e *UploadError) Unwrap() error
• type UploadInput

Constants

const (
	// ErrCodeResourceUnsupportedScheme means no handler is registered for the resource scheme.
	ErrCodeResourceUnsupportedScheme = 20200
	// ErrCodeResourceOpenUnsupported means a handler does not implement opening.
	ErrCodeResourceOpenUnsupported = 20201
	// ErrCodeResourceUploadUnsupported means a handler does not implement uploading.
	ErrCodeResourceUploadUnsupported = 20202
	// ErrCodeResourceSizeLimitExceeded means a resource body exceeded the configured size limit.
	ErrCodeResourceSizeLimitExceeded = 20203
	// ErrCodeResourceTimeoutBudgetExhausted means the current context deadline has no remaining budget.
	ErrCodeResourceTimeoutBudgetExhausted = 10120
)

Variables

var (
	// ErrUnsupportedScheme means no handler is registered for the resource scheme.
	ErrUnsupportedScheme = datax.NewError(ErrCodeResourceUnsupportedScheme, "resource: unsupported scheme", nil)
	// ErrOpenUnsupported means a handler does not implement opening.
	ErrOpenUnsupported = datax.NewError(ErrCodeResourceOpenUnsupported, "resource: open unsupported", nil)
	// ErrUploadUnsupported means a handler does not implement uploading.
	ErrUploadUnsupported = datax.NewError(ErrCodeResourceUploadUnsupported, "resource: upload unsupported", nil)
	// ErrSizeLimitExceeded means a resource body exceeded the configured size limit.
	ErrSizeLimitExceeded = datax.NewError(ErrCodeResourceSizeLimitExceeded, "resource: size limit exceeded", nil)
	// ErrTimeoutBudgetExhausted means the current context deadline has no remaining budget.
	ErrTimeoutBudgetExhausted = datax.NewError(ErrCodeResourceTimeoutBudgetExhausted, "resource: timeout budget exhausted", nil)
)

Types

type DownloadError

type DownloadError struct {
	DstPath string
	Err     error
}

DownloadError wraps download failures.

func (*DownloadError) Error

func (e *DownloadError) Error() string

Error implements error.

func (*DownloadError) Unwrap

func (e *DownloadError) Unwrap() error

Unwrap returns the root cause.

type HandlerFuncs

type HandlerFuncs struct {
	OpenFunc   func(ctx context.Context, id Identifier) (*Stream, error)
	UploadFunc func(ctx context.Context, in UploadInput) (Identifier, error)
}

HandlerFuncs adapts functions into a ResourceHandler.

func (HandlerFuncs) Open

func (h HandlerFuncs) Open(ctx context.Context, id Identifier) (*Stream, error)

Open implements ResourceHandler.

func (HandlerFuncs) Upload

func (h HandlerFuncs) Upload(ctx context.Context, in UploadInput) (Identifier, error)

Upload implements ResourceHandler.

type Identifier

type Identifier struct {
	Raw       string
	Params    map[string]string
	SourceURI string
	Scheme    string

	AuthID    string
	MediaType string
}

Identifier is the parsed form of an ofa-res resource identifier.

func Parse

func Parse(raw string) (Identifier, error)

Parse parses an ofa-res resource identifier without doing network or disk IO.

type Manager

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

Manager routes resource operations to handlers by source scheme.

func NewManager

func NewManager(opts ...Option) *Manager

NewManager creates a Manager with built-in handlers for https, data, and optionally http.

func (*Manager) Download

func (m *Manager) Download(ctx context.Context, raw string, dstPath string) error

Download opens raw and atomically writes its body to dstPath.

func (*Manager) Open

func (m *Manager) Open(ctx context.Context, raw string) (*Stream, error)

Open parses raw, routes by scheme, and returns a stream.

func (*Manager) Register

func (m *Manager) Register(scheme string, handler ResourceHandler) error

Register registers or replaces a handler for a scheme.

func (*Manager) Upload

func (m *Manager) Upload(ctx context.Context, scheme string, in UploadInput) (Identifier, error)

Upload routes an upload request to the handler registered for scheme.

type OpenError

type OpenError struct {
	Identifier Identifier
	Err        error
}

OpenError wraps resource open failures.

func (*OpenError) Error

func (e *OpenError) Error() string

Error implements error.

func (*OpenError) Unwrap

func (e *OpenError) Unwrap() error

Unwrap returns the root cause.

type Option

type Option func(*Options)

Option configures a Manager.

func WithDataMaxBytes

func WithDataMaxBytes(maxBytes int64) Option

WithDataMaxBytes sets the default data URL body size limit.

func WithHTTPClient

func WithHTTPClient(client *http.Client) Option

WithHTTPClient sets the client used by default http/https handlers.

func WithHTTPEnabled

func WithHTTPEnabled(enabled bool) Option

WithHTTPEnabled toggles the built-in http handler. https remains enabled.

func WithMaxBytes

func WithMaxBytes(maxBytes int64) Option

WithMaxBytes sets the default stream and download body size limit.

func WithRedirectLimit

func WithRedirectLimit(limit int) Option

WithRedirectLimit sets the default HTTP redirect limit.

func WithRetry

func WithRetry(attempts int, baseDelay time.Duration, maxDelay time.Duration) Option

WithRetry configures limited retries for built-in idempotent reads.

func WithTimeoutQuota

func WithTimeoutQuota(timeout time.Duration) Option

WithTimeoutQuota sets the default timeout when ctx has no deadline.

type Options

type Options struct {
	HTTPClient     *http.Client
	MaxBytes       int64
	DataMaxBytes   int64
	TimeoutQuota   time.Duration
	ConnectTimeout time.Duration
	RedirectLimit  int
	RetryAttempts  int
	RetryBaseDelay time.Duration
	RetryMaxDelay  time.Duration
	EnableHTTP     bool
}

Options controls Manager defaults and built-in handlers.

type ParseError

type ParseError struct {
	Raw string
	Err error
}

ParseError wraps resource identifier parse failures.

func (*ParseError) Error

func (e *ParseError) Error() string

Error implements error.

func (*ParseError) Unwrap

func (e *ParseError) Unwrap() error

Unwrap returns the root cause.

type ResourceHandler

type ResourceHandler interface {
	Open(ctx context.Context, id Identifier) (*Stream, error)
	Upload(ctx context.Context, in UploadInput) (Identifier, error)
}

ResourceHandler opens and uploads resources for a specific source scheme.

type Stream

type Stream struct {
	Body      io.ReadCloser
	MediaType string
	Filename  string
	Size      int64
	SourceURI string
	Headers   http.Header
}

Stream is an opened resource stream. Callers must close Body.

type UploadError

type UploadError struct {
	Scheme string
	Err    error
}

UploadError wraps upload failures.

func (*UploadError) Error

func (e *UploadError) Error() string

Error implements error.

func (*UploadError) Unwrap

func (e *UploadError) Unwrap() error

Unwrap returns the root cause.

type UploadInput

type UploadInput struct {
	Body       io.Reader
	MediaType  string
	Filename   string
	AuthID     string
	TargetHint string
}

UploadInput describes a single upload request. Body is not closed by Upload.