gistfs

README

GistFS

GistFS is an io/fs implementation that enables to read files stored in a given Gist.

Requirements

This module depends on io/fs which is only available in go 1.16 beta1. To install it, run the following commands:

go get golang.org/dl/go1.16beta1
go1.16beta1 download

# From there, just use go1.16beta1 instead of the go command
go1.16beta1 run ...

Usage

GistFS is threadsafe.

package main

import (
	"context"
	"fmt"
	"net/http"

	"github.com/jhchabran/gistfs"
)

func main() {
	// create a FS based on https://gist.github.com/jhchabran/ded2f6727d98e6b0095e62a7813aa7cf
	gfs := gistfs.New("ded2f6727d98e6b0095e62a7813aa7cf")

	// load the remote content once for all,
	// ie, no more API calls toward Github will be made.
	err := gfs.Load(context.Background())
	if err != nil {
		panic(err)
	}

	// --- base API
	// open the "test1.txt" file
	f, err := gfs.Open("test1.txt")
	if err != nil {
		panic(err)
	}

	// read its content
	b := make([]byte, 1024)
	_, err = f.Read(b)

	if err != nil {
		panic(err)
	}

	fmt.Println(string(b))

	// --- ReadFile API
	// directly read the "test1.txt" file
	b, err = gfs.ReadFile("test1.txt")
	if err != nil {
		panic(err)
	}

	fmt.Println(string(b))

	// --- ReadDir API
	// there is only one directory in a gistfile, the root dir "."
	files, err := gfs.ReadDir(".")
	if err != nil {
		panic(err)
	}

	for _, entry := range files {
		fmt.Println(entry.Name())
	}

	// --- Serve the files from the gists over http
	http.ListenAndServe(":8080", http.FileServer(http.FS(gfs)))
}

See also

• Draft design for the file system interface.
• Prototype code of io/fs
• Managing Go installations

Documentation

Index

• Variables
• type FS
  • func New(id string) *FS
  • func NewWithClient(client *github.Client, id string) *FS
  • func (fsys *FS) GetID() string
  • func (fsys *FS) Load(ctx context.Context) error
  • func (fsys *FS) Open(name string) (fs.File, error)
  • func (fsys *FS) ReadDir(name string) ([]fs.DirEntry, error)
  • func (fsys *FS) ReadFile(name string) ([]byte, error)

Variables

var ErrNotLoaded = fmt.Errorf("gist not loaded: %w", fs.ErrInvalid)

ErrNotLoaded is an error that signals that the filesystem is being used while not previously loaded.

Types

type FS

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

FS represents a filesystem based on a Github Gist.

func New

func New(id string) *FS

New returns a FS based on a given Gist ID, without the username portion. Example "https://gist.github.com/jhchabran/ded2f6727d98e6b0095e62a7813aa7cf"

id = "ded2f6727d98e6b0095e62a7813aa7cf"

func NewWithClient

func NewWithClient(client *github.Client, id string) *FS

NewWithClient returns a FS based on a given Gist ID and a given Github Client. Providing an authenticated client or a client with a custom http.Client are possible use cases.

func (*FS) GetID

func (fsys *FS) GetID() string

GetID returns the Github Gist ID that the filesystem was created with

func (*FS) Load

func (fsys *FS) Load(ctx context.Context) error

Load fetches the gist content from github, making the file system ready for use. If the underlying Github API call fails, it will return its error.

func (*FS) Open

func (fsys *FS) Open(name string) (fs.File, error)

Open opens the named file for reading and return it as an fs.File.

func (*FS) ReadDir

func (fsys *FS) ReadDir(name string) ([]fs.DirEntry, error)

ReadDir reads and returns the entire named directory, which contains all files that are stored in the Gist supporting the filesystem.

Becaus a Github Gist can't have folders, the only directory that exists is the root directory, named "." or "./".

func (*FS) ReadFile

func (fsys *FS) ReadFile(name string) ([]byte, error)

ReadFile reads and returns the content of the named file.