bucket

Documentation

Overview

Package bucket provides a consistent and unique API for bucket integrations. It mainly allows to write to and delete from a bucket.

Index

• Constants
• type Bucket
• type Config
  • func (config *Config) Validate() error
• type Handler
  • func New(ctx context.Context, from integration.Integration, config Config, ...) (*Handler, error)
  • func (h *Handler) ActivityDeleteExecution(ctx context.Context, input InputDelete) (OutputDelete, error)
  • func (h *Handler) ActivityDeleteValidation(ctx context.Context, input InputDelete) (OutputDelete, error)
  • func (h *Handler) ActivityWriteExecution(ctx context.Context, input InputWrite) (OutputWrite, error)
  • func (h *Handler) ActivityWriteValidation(ctx context.Context, input InputWrite) (OutputWrite, error)
  • func (h *Handler) Close() error
  • func (h *Handler) ConfigMap() map[string]any
  • func (h *Handler) Init() error
  • func (h *Handler) IsReady() bool
  • func (h *Handler) ListActivities() []string
  • func (h *Handler) ListWorkflows() []string
  • func (h *Handler) Register(w worker.Worker) error
  • func (h *Handler) String() string
  • func (h *Handler) WorkflowDelete(ctx workflow.Context, input InputDelete) (OutputDelete, error)
  • func (h *Handler) WorkflowWrite(ctx workflow.Context, input InputWrite) (OutputWrite, error)
• type InputDelete
  • func (input *InputDelete) Validate(config *Config) error
• type InputWrite
  • func (input *InputWrite) Validate(config *Config) error
• type OutputDelete
• type OutputWrite
• type Policies
• type With
  • func WithBucket(bucket *blob.Bucket) With
• type WriteOptions

Constants

const Specification string = "bucket"

Specification is the string representation of the bucket specification.

Types

type Bucket

type Bucket interface {

	// RegisterWithBucket allows an end-user to register the bucket specification
	// within an integration.
	RegisterWithBucket(worker.Worker, Config) error
}

Bucket is the interface used by an overlying integration to leverage the bucket specification.

type Config

type Config struct {

	// Bucket is the name of the bucket to write blobs into.
	//
	// Example: "my-bucket"
	//
	// Required.
	Bucket string `json:"bucket"`

	// Policies allows to set activity policies, such as timeouts and retries.
	Policies Policies `json:"policies"`
	// contains filtered or unexported fields
}

Config allows the end-user to configure the specification for an integration.

func (*Config) Validate

func (config *Config) Validate() error

Validate validates the config passed by the end-user when registering the specification for the overlying integration. It returns an error if anything critical occured.

type Handler

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

Handler handles the bucket specification for an integration.

func New

func New(ctx context.Context, from integration.Integration, config Config, attachments ...With) (*Handler, error)

New returns a new bucket Handler for the given integration. It applies the configuration passed by the end-user (forwarded by the integration). It also applies additional attachments an integration might leverage.

Example:

func New(myintegration, config, WithBucket(bucket))

func (*Handler) ActivityDeleteExecution

func (h *Handler) ActivityDeleteExecution(ctx context.Context, input InputDelete) (OutputDelete, error)

ActivityDeleteExecution is the activity executing the deletion in the bucket.

func (*Handler) ActivityDeleteValidation

func (h *Handler) ActivityDeleteValidation(ctx context.Context, input InputDelete) (OutputDelete, error)

ActivityDeleteValidation is the activity validating the input.

func (*Handler) ActivityWriteExecution

func (h *Handler) ActivityWriteExecution(ctx context.Context, input InputWrite) (OutputWrite, error)

ActivityWriteExecution is the activity executing the write request in the bucket.

func (*Handler) ActivityWriteValidation

func (h *Handler) ActivityWriteValidation(ctx context.Context, input InputWrite) (OutputWrite, error)

ActivityWriteValidation is the activity validating the input.

func (*Handler) Close

func (h *Handler) Close() error

Close tries to properly close the specification. An error is returned in case the Handler has already been closed.

func (*Handler) ConfigMap

func (h *Handler) ConfigMap() map[string]any

ConfigMap transforms the configuration to a map, including a "from" key with the configuration of the overlying integration.

func (*Handler) Init

func (h *Handler) Init() error

Init initializes the specification. An error is returned in case the Handler has already been initialized.

func (*Handler) IsReady

func (h *Handler) IsReady() bool

IsReady indicates if the specification is ready to be consumed by the overlying integration. The specification must be initialized, must not be closed, and must have registered its workflows and activities in the Temporal worker.

func (*Handler) ListActivities

func (h *Handler) ListActivities() []string

ListActivities returns a sorted list of activities' name registered by the specification for the overlying integration.

func (*Handler) ListWorkflows

func (h *Handler) ListWorkflows() []string

ListWorkflows returns a sorted list of workflows' name registered by the specification for the overlying integration.

func (*Handler) Register

func (h *Handler) Register(w worker.Worker) error

Register registers the specification's workflows and activities in the given Temporal worker. An error is returned in case the registration has already been made.

func (*Handler) String

func (h *Handler) String() string

String returns the string representation of the overlying integration.

func (*Handler) WorkflowDelete

func (h *Handler) WorkflowDelete(ctx workflow.Context, input InputDelete) (OutputDelete, error)

WorkflowDelete is a high-level opiniated Temporal workflow. It executes the following activities:

1. ActivityDeleteValidation: Validates the input (local activity).

2. ActivityDeleteExecution: Executes the request against the third-party service to delete data from the bucket.

func (*Handler) WorkflowWrite

func (h *Handler) WorkflowWrite(ctx workflow.Context, input InputWrite) (OutputWrite, error)

WorkflowWrite is a high-level opiniated Temporal workflow. It executes the following activities:

1. ActivityWriteValidation: Validates the input (local activity).

2. ActivityWriteRequest: Executes the request against the third-party service to write data in the bucket.

type InputDelete

type InputDelete struct {

	// Policies passed in the input can override the ones set when creating the
	// specification. It will only apply if allowed in the integration's Config
	// via AllowPoliciesOverride.
	Policies *Policies `json:"policies"`

	// Context represents the event's context, shared across every specifications
	// and integrations of this ecosystem.
	Context *event.Context `json:"context,omitempty"`

	// Path is the path and key of the blob to delete at.
	//
	// Example: "path/to/key.json"
	//
	// Required.
	Path string `json:"path"`
}

InputDelete is the input for the "Delete" workflow and activities.

func (*InputDelete) Validate

func (input *InputDelete) Validate(config *Config) error

Validate can be used to validate the workflow/activity's input. It's the validation function used in the local activity ActivityDeleteValidation.

type InputWrite

type InputWrite struct {

	// Policies passed in the input can override the ones set when creating the
	// specification. It will only apply if allowed in the integration's Config
	// via AllowPoliciesOverride.
	Policies *Policies `json:"policies"`

	// Context represents the event's context, shared across every specifications
	// and integrations of this ecosystem.
	Context *event.Context `json:"context,omitempty"`

	// Options allows the end-users to pass options to the blob when writing it
	// into the bucket.
	Options WriteOptions `json:"options,omitempty"`

	// Path is the path and key of the blob to write at.
	//
	// Example: "path/to/key.json"
	//
	// Required.
	Path string `json:"path"`

	// Blob is byte representation of the blob to write at Path.
	//
	// Required.
	Blob []byte `json:"blob"`
}

InputWrite is the input for the "Write" workflow and activities.

func (*InputWrite) Validate

func (input *InputWrite) Validate(config *Config) error

Validate can be used to validate the workflow/activity's input. It's the validation function used in the local activity ActivityWriteValidation.

type OutputDelete

type OutputDelete struct {

	// Status is the status of the workflow or activity. It's one of "success",
	// "failure".
	Status lifecycle.Status `json:"status"`
}

OutputDelete is the output for the "Delete" workflow and activities.

type OutputWrite

type OutputWrite struct {

	// Status is the status of the workflow or activity. It's one of "success",
	// "failure".
	Status lifecycle.Status `json:"status"`
}

OutputWrite is the output for the "Write" workflow and activities.

type Policies

type Policies struct {

	// Execution is the policy to apply by the activity used to write or delete
	// a blob.
	//
	// Note: Since this is a short-live policy, activity's heartbeat is not used.
	// Therefore, Execution.HeartbeatTimeout is not applied. We advise to set a
	// short-live Execution.SingleAttemptTimeout, such as 3 seconds.
	Execution lifecycle.ActivityPolicy `json:"execution"`
	// contains filtered or unexported fields
}

Policies represents the Temporal activity policies to apply within the workflows exposed by this package and the overlying integration.

type With

type With func(*Handler) error

With allows an integration to customize the behavior of the specification. It's in addition to Config. Since Config is designed for — and accessible by — end-users, With is specifically designed for integrations.

For example, an integration must call WithBucket to attach the *blob.Bucket:

func New(myintegration, config, WithBucket(bucket))

func WithBucket

func WithBucket(bucket *blob.Bucket) With

WithBucket must be passed to New to attach the *blob.Bucket from the overlying integration:

func New(myintegration, config, WithBucket(bucket))

type WriteOptions

type WriteOptions struct {

	// CacheControl specifies caching attributes that services may use when serving
	// the blob. More info at:
	// https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control.
	CacheControl string `json:"cache,omitempty"`

	// ContentDisposition specifies whether the blob content is expected to be
	// displayed inline or as an attachment. More info at:
	// https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition.
	ContentDisposition string `json:"disposition,omitempty"`

	// ContentEncoding specifies the encoding used for the blob's content, if any.
	// More info at: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Encoding.
	ContentEncoding string `json:"encoding,omitempty"`

	// ContentLanguage specifies the language used in the blob's content, if any.
	// More info at: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Language.
	ContentLanguage string `json:"language,omitempty"`

	// ContentType specifies the MIME type of the blob being written. If not set,
	// it will be inferred from the content using the algorithm described at
	// http://mimesniff.spec.whatwg.org/. More info at:
	// https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type.
	ContentType string `json:"type,omitempty"`

	// ContentMD5 is used as a message integrity check. If len(ContentMD5) > 0,
	// the MD5 hash of the bytes written must match ContentMD5, or the activity
	// will return an error without completing the write. More info at:
	// https://tools.ietf.org/html/rfc1864.
	ContentMD5 []byte `json:"md5,omitempty"`
}

WriteOptions represents the options an end-user can pass when writing a blob into a bucket. These options can be leveraged by the integration to attach some metadata or check the consistency of the blob for example.