file

Documentation

Overview

package file provides functions that can be used to retrieve files from local and remote locations.

Index

• func Get(ctx context.Context, location string) (string, error)
• type Path
  • func (p Path) New() string

Examples

• Get (Http)
• Get (Local)

Functions

func Get

func Get(ctx context.Context, location string) (string, error)

Get retrieves a file from these locations (in order):

- Local disk

- HTTP or HTTPS URL

- AWS S3

If a file is found, then it is saved as a temporary local file and the name is returned. The caller is responsible for removing files when they are no longer needed; files should be removed even if an error occurs.

Example (Http)

package main

import (
	"context"
	"fmt"
	"os"
	"strings"

	"github.com/brexhq/substation/internal/file"
)

func main() {
	location := "https://example.com"

	// a local copy of the HTTP body is created and must be removed when it's no longer needed, regardless of errors
	path, err := file.Get(context.TODO(), location)
	defer os.Remove(path)

	if err != nil {
		// handle err
		panic(err)
	}

	f, err := os.Open(path)
	if err != nil {
		// handle err
		panic(err)
	}

	defer f.Close()

	buf := make([]byte, 16)
	if _, err = f.Read(buf); err != nil {
		// handle err
		panic(err)
	}

	prefix := strings.HasPrefix(strings.ToUpper(string(buf)), "<!DOCTYPE")
	fmt.Println(prefix)

}

Output:

true

Example (Local)

package main

import (
	"context"
	"fmt"
	"io"
	"os"

	"github.com/brexhq/substation/internal/file"
)

func main() {
	// temp file is used to simulate an open file and must be removed after the test completes
	temp, _ := os.CreateTemp("", "substation")
	defer os.Remove(temp.Name())
	defer temp.Close()

	_, _ = temp.Write([]byte("foo\nbar\nbaz"))

	// a local copy of the file is created and must be removed when it's no longer needed, regardless of errors
	path, err := file.Get(context.TODO(), temp.Name())
	defer os.Remove(path)

	if err != nil {
		// handle err
		panic(err)
	}

	f, err := os.Open(path)
	if err != nil {
		// handle err
		panic(err)
	}

	defer f.Close()

	buf, err := io.ReadAll(f)
	if err != nil {
		// handle err
		panic(err)
	}

	fmt.Println(string(buf))

}

Output:

foo
bar
baz

Types

type Path

type Path struct {
	// Prefix prepends a value to the file path.
	//
	// This is optional and has no default.
	Prefix string `json:"prefix"`
	// TimeFormat inserts a formatted datetime string into the file path.
	// Must be one of:
	//   - pattern-based layouts (https://gobyexample.com/procTime-formatting-parsing)
	//   - unix: epoch (supports fractions of a second)
	//   - unix_milli: epoch milliseconds
	//
	// This is optional and has no default.
	TimeFormat string `json:"time_format"`
	// UUID inserts a random UUID into the file path. If a suffix is
	// not set, then this is used as the filename.
	//
	// This is optional and defaults to false.
	UUID bool `json:"uuid"`
	// Suffix appends a value to the file path.
	//
	// This is optional and has no default.
	Suffix string `json:"suffix"`
}

func (Path) New

func (p Path) New() string

New constructs a file path using the pattern [p.Prefix]/[p.TimeFormat]/[p.UUID][p.Suffix], where each field is optional and builds on the previous field. The caller is responsible for creating an OS agnostic file path (filepath.FromSlash is recommended).

If only one field is set, then this constructs a filename, otherwise it constructs a file path.

If the struct is empty, then this returns an empty string. The caller is responsible for creating a default file path if needed.