file

Documentation

Overview

Package file abstracts non-hierarchical file stores. Each file consists of a name, a MIME type, a UUID, and data. File names may be duplicate.

TODO: think about name vs. UUID again—should the “name” really be the filename and not the UUID?

Index

• Variables
• func StoreFromHTTP(fs FS, r *http.Request, key string) error
• type FS
• type FSInfo
  • func (i *FSInfo) Create() (FS, error)
• type FileInfo

Examples

• FS
• StoreFromHTTP

Variables

var (
	ErrInvalidFSType        = errors.New("invalid file store type")
	ErrNoFSRoot             = errors.New("no file store root")
	ErrNotImplementedFSType = errors.New("FSInfo.Create not implemented for provided file store type")
)

errors

Functions

func StoreFromHTTP

func StoreFromHTTP(fs FS, r *http.Request, key string) error

StoreFromHTTP stores the first file with given form key from an HTTP multipart/form-data request. Its Content-Type header is ignored; the type is detected. The file name is the last part of the provided file name not containing any slashes or backslashes.

TODO: store all files with the given key instead of just the first one

Example

package main

import (
	"fmt"
	"net/http"

	"codeberg.org/genofire/golang-lib/web/file"
)

var fstore file.FS

func main() {
	http.HandleFunc("/upload", func(w http.ResponseWriter, r *http.Request) {
		if err := file.StoreFromHTTP(fstore, r, "file"); err != nil {
			w.Header().Set("content-type", "application/json")
			w.WriteHeader(http.StatusInternalServerError)
			w.Write([]byte(fmt.Sprintf(`{"message":"%v"}`, err)))
		} else {
			w.WriteHeader(http.StatusOK)
		}
	})
}

Types

type FS

type FS interface {
	// Store stores a new file with the given UUID, name, and MIME type.
	// Its data is taken from the provided Reader. If it encounters an
	// error, it does nothing. Any existing file with the same UUID is
	// overwritten.
	Store(id uuid.UUID, name, contentType string, data io.Reader) error
	// RemoveUUID deletes a file.
	RemoveUUID(id uuid.UUID) error
	// Open opens a file by its name. If multiple files have the same name,
	// it is unspecified which one is opened. This may very well be very
	// slow. This is bad. Go away.
	Open(name string) (fs.File, error)
	// OpenUUID opens a file by its UUID.
	OpenUUID(id uuid.UUID) (fs.File, error)
	// Check checks the health of the file store. If the file store is not
	// healthy, it returns a descriptive error. Otherwise, the file store
	// should be usable.
	Check() error
}

An FS is a file store.

Example

package main

import (
	"io"
	"os"

	"github.com/google/uuid"

	"codeberg.org/genofire/golang-lib/web/file"
)

var fstore file.FS

func main() {
	// generate the UUID for the new file
	id := uuid.New()

	// store a file
	{
		f, _ := os.Open("glenda.png")
		fstore.Store(id, "glenda.png", "image/png", f)
		f.Close()
	}

	// copy back to a local file
	{
		r, _ := fstore.OpenUUID(id)
		w, _ := os.Create("glenda.png")
		io.Copy(w, r)
		r.Close()
		w.Close()
	}
}

type FSInfo

type FSInfo struct {
	FSType fsType `config:"type" toml:"type"`
	// file system
	Root string `config:",omitempty" toml:",omitempty"`
	// s3
	Endpoint string `config:",omitempty" toml:",omitempty"`
	Secure   bool   `config:",omitempty" toml:",omitempty"`
	ID       string `config:",omitempty" toml:",omitempty"`
	Secret   string `config:",omitempty" toml:",omitempty"`
	Bucket   string `config:",omitempty" toml:",omitempty"`
	Location string `config:",omitempty" toml:",omitempty"`
}

FSInfo is a TOML structure storing access information about a file store.

func (*FSInfo) Create

func (i *FSInfo) Create() (FS, error)

Create creates a file store from the information provided.

type FileInfo

type FileInfo interface {
	fs.FileInfo
	ID() uuid.UUID
	ContentType() string
}