windlass

README

windlass

A Go library for multipart file uploads.

Inspired by tus and S3 multipart upload but with a no-nonsense approach.

Features

• Resumable multipart uploads.
• All metadata is stored in the filesystem.
• No database required.

Usage

See server.go for how to implement a windlass server.

Information about how to use the windlass client can be found in the end-to-end tests in upload_test.go.

Clients

• windlass-js - A TypeScript client for windlass.

Documentation

Index

• type Client
  • func NewClient(logger *slog.Logger, uploadURL string, opts *ClientOptions) (*Client, error)
  • func (c *Client) Upload(ctx context.Context, path string, r io.ReaderAt, size int64) error
• type ClientOptions
• type Server
  • func NewServer(logger *slog.Logger, fsys writablefs.FS, opts ...ServerOption) *Server
  • func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type ServerOption
  • func WithStagingFS(fsys writablefs.FS) ServerOption

Types

type Client

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

Client is a reslient upload client.

func NewClient

func NewClient(logger *slog.Logger, uploadURL string, opts *ClientOptions) (*Client, error)

func (*Client) Upload

func (c *Client) Upload(ctx context.Context, path string, r io.ReaderAt, size int64) error

Upload uploads a file to the server, you must provide a ReaderAt so that we can upload chunks concurrently.

type ClientOptions

type ClientOptions struct {
	// NumConnections is the number of concurrent connections to use when uploading chunks.
	NumConnections int
	// ChunkSizeBytes is the size of each chunk.
	ChunkSizeBytes int64
	// MaxRetryAttempts is the maximum number of times to retry a failed request.
	MaxRetryAttempts int
	// RequestTimeout is the timeout to use when making requests (eg. dialing, TLS handshake, etc).
	RequestTimeout time.Duration
	// TLSClientConfig is the optional TLS configuration to use when making requests.
	TLSClientConfig *tls.Config
}

ClientOptions are options for configuring the behavior of the upload client.

type Server

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

Server is a windlass files server.

func NewServer

func NewServer(logger *slog.Logger, fsys writablefs.FS, opts ...ServerOption) *Server

func (*Server) ServeHTTP

func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)

type ServerOption

type ServerOption func(*Server)

ServerOption is an option for configuring a windlass server.

func WithStagingFS

func WithStagingFS(fsys writablefs.FS) ServerOption

WithStagingFS sets the staging filesystem to use for storing partial uploads. If not provided, the default filesystem will be used. This is useful for filesystems that only support immutable files, such as S3.