vercel_blob

README

Go Vercel Blob Client

This is a Golang package that has been transcribed from vercel_blob, aiming to provide similar functionality and features.

I personally extend sincere thanks and appreciation to the original author for their Rust package, which has served as a valuable foundation. If you are interested in the original author's Rust package, please visit the following link: https://github.com/lancedb/vercel_blob

Authentication

Within your application

If your golang code is part of a golang serverless function then authentication is automatic and provided as a part of the vercel runtime.

Outside your application

If your golang code is part of a client package (running in the browser via wasm or running some kind of custom client application) then you will need to obtain an authentication token. This can be done by creating a route in your server that will supply short-lived authentication tokens to authorized users.

Documentation

Index

• Constants
• Variables
• func GetToken(provider TokenProvider, operation, pathname string) (string, error)
• type BlobApiError
• type BlobApiErrorDetail
• type DownloadCommandOptions
• type EnvTokenProvider
  • func NewEnvTokenProvider(envVar string) (*EnvTokenProvider, error)
  • func (p *EnvTokenProvider) GetToken(operation, pathname string) (string, error)
• type HeadBlobResult
• type ListBlobResult
• type ListBlobResultBlob
• type ListCommandOptions
• type PutBlobPutResult
• type PutCommandOptions
• type Range
• type TokenProvider
• type VercelBlobClient
  • func NewVercelBlobClient() *VercelBlobClient
  • func NewVercelBlobClientExternal(tokenProvider TokenProvider) *VercelBlobClient
  • func (c *VercelBlobClient) Copy(fromUrl, toPath string, options PutCommandOptions) (*PutBlobPutResult, error)
  • func (c *VercelBlobClient) Delete(urlPath string) error
  • func (c *VercelBlobClient) Download(urlPath string, options DownloadCommandOptions) ([]byte, error)
  • func (c *VercelBlobClient) Head(pathname string) (*HeadBlobResult, error)
  • func (c *VercelBlobClient) List(options ListCommandOptions) (*ListBlobResult, error)
  • func (c *VercelBlobClient) Put(pathname string, body io.Reader, options PutCommandOptions) (*PutBlobPutResult, error)
• type VercelBlobError
  • func NewInvalidInputError(field string) VercelBlobError
  • func NewUnknownError(statusCode int, message string) VercelBlobError
  • func (e VercelBlobError) Error() string

Constants

const (
	BLOB_API_VERSION = "4"
	DEFAULT_BASE_URL = "https://blob.vercel-storage.com"
)

Variables

var (
	ErrNotAuthenticated = &VercelBlobError{
		Msg:  "No authentication token. Expected environment variable BLOB_READ_WRITE_TOKEN to contain a token",
		Code: "not_authenticated",
	}

	ErrBadRequest = func(msg string) VercelBlobError {
		return VercelBlobError{
			Msg:  fmt.Sprintf("Invalid request: %s", msg),
			Code: "bad_request",
		}
	}

	ErrForbidden = &VercelBlobError{
		Msg:  "Access denied, please provide a valid token for this resource",
		Code: "forbidden",
	}

	ErrStoreNotFound = &VercelBlobError{
		Msg:  "The requested store does not exist",
		Code: "store_not_found",
	}

	ErrStoreSuspended = &VercelBlobError{
		Msg:  "The requested store has been suspended",
		Code: "store_suspended",
	}

	ErrBlobNotFound = &VercelBlobError{
		Msg:  "The requested blob does not exist",
		Code: "not_found",
	}
)

All errors raised by this crate will be instances of VercelBlobError

Functions

func GetToken

func GetToken(provider TokenProvider, operation, pathname string) (string, error)

Types

type BlobApiError

type BlobApiError struct {
	Error BlobApiErrorDetail `json:"error"`
}

type BlobApiErrorDetail

type BlobApiErrorDetail struct {
	Code    string `json:"code"`
	Message string `json:"message"`
}

type DownloadCommandOptions

type DownloadCommandOptions struct {
	// The range of bytes to download.  If not specified then the entire blob
	// is downloaded.  The start of the range must be less than the # of bytes
	// in the blob or an error will be returned.  The end of the range may be
	// greater than the number of bytes in the blob.
	ByteRange *Range
}

DownloadCommandOptions is options for the download operation

type EnvTokenProvider

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

EnvTokenProvider is a token provider that reads the token from an environment variable.

This is useful for testing but should not be used for real applications.

func NewEnvTokenProvider

func NewEnvTokenProvider(envVar string) (*EnvTokenProvider, error)

func (*EnvTokenProvider) GetToken

func (p *EnvTokenProvider) GetToken(operation, pathname string) (string, error)

type HeadBlobResult

type HeadBlobResult struct {
	// The URL to download the blob
	URL string `json:"url"`
	// The size of the blob in bytes
	Size uint64 `json:"size"`
	// The time the blob was uploaded
	UploadedAt time.Time `json:"uploadedAt"`
	// The pathname of the blob
	Pathname string `json:"pathname"`
	// The content type of the blob
	ContentType string `json:"contentType"`
	// The content disposition of the blob
	ContentDisposition string `json:"contentDisposition"`
	// The cache settings for the blob
	CacheControl string `json:"cacheControl"`
}

HeadBlobResult is response from the head operation

type ListBlobResult

type ListBlobResult struct {
	// A list of blobs found by the operation
	Blobs []ListBlobResultBlob `json:"blobs"`
	// A cursor that can be used to page results
	Cursor string `json:"cursor"`
	// True if there are more results available
	HasMore bool `json:"hasMore"`
}

ListBlobResult is the response from the list operation

type ListBlobResultBlob

type ListBlobResultBlob struct {
	// The URL to download the blob
	URL string `json:"url"`
	// The pathname of the blob
	PathName string `json:"pathname"`
	// The size of the blob in bytes
	Size uint64 `json:"size"`
	// The time the blob was uploaded
	UploadedAt time.Time `json:"uploadedAt"`
}

ListBlobResultBlob is details about a blob that are returned by the list operation

type ListCommandOptions

type ListCommandOptions struct {
	// The maximum number of results to return
	Limit uint64
	// A prefix to filter results
	Prefix string
	// A cursor (returned from a previous list call) used to page results
	Cursor string
}

ListCommandOptions is options for the list operation

The limit option can be used to limit the number of results returned. If the limit is reached then response will have has_more set to true and the cursor can be used to get the next page of results.

type PutBlobPutResult

type PutBlobPutResult struct {
	// The URL to download the blob
	URL string `json:"url"`
	// The pathname of the blob
	Pathname string `json:"pathname"`
	// The content type of the blob
	ContentType string `json:"contentType"`
	// The content disposition of the blob
	ContentDisposition string `json:"contentDisposition"`
}

PutBlobPutResult is the response from the put operation

type PutCommandOptions

type PutCommandOptions struct {
	AddRandomSuffix    bool
	CacheControlMaxAge uint64
	ContentType        string
}

PutCommandOptions is options for the put operation

By default uploaded files are assigned a URL with a random suffix. This ensures that no put operation will overwrite an existing file. The url returned in the response can be used to later download the file.

If predictable URLs are needed then add_random_suffix can be set to false to disable this behavior. If dsiabled then sequential writes to the same pathname will overwrite each other.

type Range

type Range struct {
	Start uint
	End   uint
}

type TokenProvider

type TokenProvider interface {
	GetToken(operation string, pathname string) (string, error)
}

TokenProvider is a trait for providing a token to authenticate with the Vercel Blob Storage API.

If your code is running inside a Vercel function then you will not need this.

If your code is running outside of Vercel (e.g. a client application) then you will need to obtain a token from your Vercel application. You can create a route to provide short-term tokens to authenticated users. This trait allows you to connect to that route (or use some other method to obtain a token).

The operation (e.g. list, put, download) and pathname (e.g. foo/bar.txt) are provided in case fine-grained authorization is required. For operations that use the full URL (download / del) the pathname will be the URL.

type VercelBlobClient

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

func NewVercelBlobClient

func NewVercelBlobClient() *VercelBlobClient

NewVercelBlobClient creates a new client for use inside a Vercel function

func NewVercelBlobClientExternal

func NewVercelBlobClientExternal(tokenProvider TokenProvider) *VercelBlobClient

NewVercelBlobClientExternal creates a new client for use outside of Vercel

func (*VercelBlobClient) Copy

func (c *VercelBlobClient) Copy(fromUrl, toPath string, options PutCommandOptions) (*PutBlobPutResult, error)

func (*VercelBlobClient) Delete

func (c *VercelBlobClient) Delete(urlPath string) error

Delete a blob from the blob store

Arguments

• `urlPath` - The URL of the file to delete. This should be the same URL that is used to download the file.
• `options` - Options for the del operation

Returns

None

func (*VercelBlobClient) Download

func (c *VercelBlobClient) Download(urlPath string, options DownloadCommandOptions) ([]byte, error)

Download a blob from the blob store

Arguments

* `urlPath` - The URL of the file to download. * `options` - Options for the download operation

Returns

The contents of the file

func (*VercelBlobClient) Head

func (c *VercelBlobClient) Head(pathname string) (*HeadBlobResult, error)

Head gets the metadata for a file in the blob store

Arguments

• `pathname` - The URL of the file to get metadata for. This should be the same URL that is used to download the file.
• `options` - Options for the head operation

Returns

If the file exists then the metadata for the file is returned. If the file does not exist then None is returned.

func (*VercelBlobClient) List

func (c *VercelBlobClient) List(options ListCommandOptions) (*ListBlobResult, error)

List files in the blob store

Arguments

* `options` - Options for the list operation

Returns

The response from the list operation

func (*VercelBlobClient) Put

func (c *VercelBlobClient) Put(pathname string, body io.Reader, options PutCommandOptions) (*PutBlobPutResult, error)

Put uploads a file to the blob store

Arguments

* `pathname` - The destination pathname for the uploaded file * `body` - The contents of the file * `options` - Options for the put operation

Returns

The response from the put operation. This includes a URL that can be used to later download the blob.

type VercelBlobError

type VercelBlobError struct {
	Msg  string
	Code string
}

VercelBlobError will be the type of all errors raised by this crate.

func NewInvalidInputError

func NewInvalidInputError(field string) VercelBlobError

func NewUnknownError

func NewUnknownError(statusCode int, message string) VercelBlobError

func (VercelBlobError) Error

func (e VercelBlobError) Error() string