README
¶
ghrfs: The GitHub Release File System
A go fs.FS driver that reads from GitHub releases.
Description
ghrfs (short for GitHub Release File System) is a Go fs.FS implementation that reads data from a GitHub release.
The ReleaseFileystem object emulates a read-only filesystem by reading from
GitHub's API or from a local cache for faster access with less bandwidth consumption
or to support switching to airgapped environments.
Install
go get github.com/carabiner-dev/ghrfs
Usage
Authentication
The filesystems requires GitHub credentials to access the GitHub API. By default
it will look for an API token in the GITHUB_TOKEN environment variable. ghrfs
is based on carabiner-dev/github which
means you should be able to use any token provider that the client supports.
Example Use
To use the filesystem, simply initialize a new instance and use with anything that
takes a fs.FS:
package main
import (
"fmt"
"io"
"os"
"github.com/carabiner-dev/ghrfs"
)
func main() {
// Create a new GitHub Release File System:
rfs, err := ghrfs.New(
ghrfs.FromURL("https://github.com/carabiner-dev/ghrfs/releases/tag/v0.0.0"),
)
if err != nil {
fmt.Println(err.Error())
os.Exit(1)
}
// Open a file from the release:
file, err := rfs.Open("about-this-release.txt")
if err != nil {
fmt.Println(err.Error())
os.Exit(1)
}
// Get information about the file:
info, err := file.Stat()
if err != nil {
fmt.Println(err.Error())
os.Exit(1)
}
// Do something with the file:
fmt.Printf("%s atrributes: %+v\n", info.Name(), info)
fmt.Println("File contents:")
io.Copy(os.Stdout, file)
}
Contribute!
This module is released under the Apache 2.0 license. Feel free to contribute improvements and report any problems you find by creating issues.
Documentation
¶
Overview ¶
Package ghrfs (short for GitHub Release File System) is an fs.FS implementation that reads data from a GitHub release.
ghrfs can read directly from GitHub's API or cache a release locally for faster access with less bandwisth consumption or to support switching to airgapped environments.
Index ¶
- func FromURL(urlString string) optFunc
- func Type() fs.FileMode
- func WithCache(useCache bool) optFunc
- func WithCacheExtensions(exts []string) optFunc
- func WithCacheMaxSize(size int64) optFunc
- func WithCachePath(path string) optFunc
- func WithHost(hostname string) optFunc
- func WithOrganization(org string) optFunc
- func WithParallelDownloads(dl int) optFunc
- func WithRepository(repo string) optFunc
- func WithTag(tag string) optFunc
- type AssetFile
- type FileInfo
- type Options
- type ReleaseData
- type ReleaseDir
- func (rd *ReleaseDir) Close() error
- func (rd *ReleaseDir) Info() (FileInfo, error)
- func (*ReleaseDir) IsDir() bool
- func (rd *ReleaseDir) Name() string
- func (rd *ReleaseDir) Read([]byte) (int, error)
- func (rd *ReleaseDir) ReadDir(n int) ([]fs.DirEntry, error)
- func (rd *ReleaseDir) Stat() (fs.FileInfo, error)
- type ReleaseFileSystem
- func (rfs *ReleaseFileSystem) CacheRelease() error
- func (rfs *ReleaseFileSystem) LoadRelease() error
- func (rfs *ReleaseFileSystem) Open(name string) (fs.File, error)
- func (rfs *ReleaseFileSystem) OpenCachedFile(name string) (fs.File, error)
- func (rfs *ReleaseFileSystem) OpenRemoteFile(name string) (fs.File, error)
- func (rfs *ReleaseFileSystem) ReadDir(name string) ([]fs.DirEntry, error)
- func (rfs *ReleaseFileSystem) Stat(name string) (fs.FileInfo, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func FromURL ¶ added in v0.1.0
func FromURL(urlString string) optFunc
FromURL intializaes thew options set from a github release URL
func WithCacheExtensions ¶ added in v0.3.0
func WithCacheExtensions(exts []string) optFunc
func WithCacheMaxSize ¶ added in v0.3.0
func WithCacheMaxSize(size int64) optFunc
func WithCachePath ¶
func WithCachePath(path string) optFunc
func WithOrganization ¶
func WithOrganization(org string) optFunc
func WithParallelDownloads ¶ added in v0.1.0
func WithParallelDownloads(dl int) optFunc
func WithRepository ¶
func WithRepository(repo string) optFunc
Types ¶
type AssetFile ¶
type AssetFile struct {
DataStream io.ReadCloser
URL string `json:"browser_download_url"`
ID int64 `json:"id"`
FileInfo
// contains filtered or unexported fields
}
AssetFile abstracts an asset stored in a GitHub release and implements fs.File by reading data from an io.ReadCloser
type FileInfo ¶
type FileInfo struct {
IName string `json:"name"` // base name of the file
ISize int64 `json:"size"` // length in bytes for regular files; system-dependent for others
Ctime time.Time `json:"created_at"`
Mtime time.Time `json:"updated_at"`
IIsDir bool `json:"isdir"`
}
FileInfo captures the asset information and implements fs.FileInfo
type Options ¶
type Options struct {
Cache bool
ParallelDownloads int
Host string
Organization string
Repository string
CachePath string
CacheMaxSize int64
CacheExtensions []string
Tag string
}
Options is the configuration struct for the github FS
type ReleaseData ¶
type ReleaseData struct {
ID int64 `json:"id"`
URL string `json:"url"`
Tag string `json:"tag_name"`
Draft bool `json:"draft"`
PublishedAt time.Time `json:"published_at"`
CreatedAt time.Time `json:"created_at"`
Assets []*AssetFile `json:"assets"`
// contains filtered or unexported fields
}
ReleaseData captures the release information from github
type ReleaseDir ¶ added in v0.2.0
ReleaseDir implements the DirEntry interface abstracting the release as as directory.
func (*ReleaseDir) Close ¶ added in v0.2.0
func (rd *ReleaseDir) Close() error
func (*ReleaseDir) Info ¶ added in v0.2.0
func (rd *ReleaseDir) Info() (FileInfo, error)
func (*ReleaseDir) IsDir ¶ added in v0.2.0
func (*ReleaseDir) IsDir() bool
func (*ReleaseDir) Name ¶ added in v0.2.0
func (rd *ReleaseDir) Name() string
type ReleaseFileSystem ¶
type ReleaseFileSystem struct {
Options Options
Release ReleaseData
// contains filtered or unexported fields
}
ReleaseFileSystem implements fs.FS by reading data a GitHub release.
func New ¶
func New(optFns ...optFunc) (*ReleaseFileSystem, error)
func NewWithOptions ¶
func NewWithOptions(opts *Options) (*ReleaseFileSystem, error)
NewWithOptions takes an options set and return a new RFS
func (*ReleaseFileSystem) CacheRelease ¶
func (rfs *ReleaseFileSystem) CacheRelease() error
CacheRelease downloads `ParallelDownloads` assets at a time and caches them in `Options.CachePath`. Each asset file's data stream is copied to a local file. If assets already have a DataStream defined, it is reused for copying and it will be closed to be replaced by the new local file when it is used.
func (*ReleaseFileSystem) LoadRelease ¶
func (rfs *ReleaseFileSystem) LoadRelease() error
LoadRelease queries the GitHub API and loads the release data, optionally catching the assets
func (*ReleaseFileSystem) Open ¶
func (rfs *ReleaseFileSystem) Open(name string) (fs.File, error)
Open opens a file.
func (*ReleaseFileSystem) OpenCachedFile ¶
func (rfs *ReleaseFileSystem) OpenCachedFile(name string) (fs.File, error)
OpenCachedFile returns an asset file with its data source connected to a local cached file
func (*ReleaseFileSystem) OpenRemoteFile ¶
func (rfs *ReleaseFileSystem) OpenRemoteFile(name string) (fs.File, error)
OpenRemoteFile returns the asset file connected to its data stream
Source Files
Directories