usher

README

Usher

Usher is a tiny personal Url SHortenER that manages a simple local database of code => url mappings, stored in a YAML text file.

Usher mappings can be published to various backends (currently Amazon S3 and render.com) to provide the actual redirection services.

Installation

go get github.com/gavincarr/usher/cmd/usher

Usage

Initialise a new database for the domain you want to use

usher init example.me

Add, list, update, and remove mappings

# Add a mapping with an explicit code (both url+code and code+url work)
usher add https://github.com/gavincarr/usher usher
usher add github https://github.com/gavincarr/usher

# Add a mapping with a randomly generated code
usher add https://github.com/gavincarr/usher

# List current mappings
usher ls

# Update an existing mapping to a new url
usher update github https://github.com/gavincarr

# Delete a mapping
usher rm github

Configure and publish to desired backend

# Report locations of usher root directory, config and database
usher root
usher config
usher db

# Configure a backend to push to (`type: s3` or `type: render`) e.g.
$EDITOR $(usher config)

# Push current mappings to your backend
usher push

Help

usher -h

Author and Licence

Copyright 2020 Gavin Carr gavin@openfusion.com.au.

usher is available under the terms of the MIT Licence.

Documentation

Index

• Variables
• type Config
• type ConfigEntry
• type DB
  • func NewDB(domain string) (*DB, error)
  • func (db *DB) Add(url, code string) (string, error)
  • func (db *DB) Init() (dbCreated bool, err error)
  • func (db *DB) List(glob string) ([]Entry, error)
  • func (db *DB) Push() error
  • func (db *DB) Remove(code string) error
  • func (db *DB) Update(url, code string) error
• type Entry
• type Route
• type Service

Variables

var (
	ErrNotFound   = errors.New("not found")
	ErrCodeExists = errors.New("code already used")
	ErrNoChange   = errors.New("mapping unchanged")
)

Types

type Config

type Config struct {
	Services []Service `yaml:"services"`
}

type ConfigEntry

type ConfigEntry struct {
	Type      string `yaml:"type"`
	AWSKey    string `yaml:"aws_key,omitempty"`
	AWSSecret string `yaml:"aws_secret,omitempty"`
	AWSRegion string `yaml:"aws_region,omitempty"`
}

type DB

type DB struct {
	Root       string // full path to usher root directory containing databases
	Domain     string // fully-qualified domain whose mappings we want
	DBPath     string // full path to database for Domain
	ConfigPath string // full path to usher config file
}

func NewDB

func NewDB(domain string) (*DB, error)

NewDB creates a DB struct with members derived from parameters, the environment, or defaults (in that order). It does no checking that the values produced are sane or exist on the filesystem.

func (*DB) Add

func (db *DB) Add(url, code string) (string, error)

Add a mapping for url and code to the database. If code is missing, a random code will be generated and returned.

func (*DB) Init

func (db *DB) Init() (dbCreated bool, err error)

Init checks and creates the following, if they don't exist: - an usher root directory - an usher database for the db.Domain - an entry in the user config file for db.Domain

func (*DB) List

func (db *DB) List(glob string) ([]Entry, error)

List returns the set of database entries whose code matches glob

func (*DB) Push

func (db *DB) Push() error

Push syncs all current mappings with the backend configured for db.Domain in db.ConfigPath

func (*DB) Remove

func (db *DB) Remove(code string) error

Remove the mapping with code from the database Returns ErrNotFound if code does not exist in the database

func (*DB) Update

func (db *DB) Update(url, code string) error

Update an existing mapping in the database, changing the URL.

type Entry

type Entry struct {
	Code string
	Url  string
}

type Route

type Route struct {
	Type        string `yaml:"type"`
	Source      string `yaml:"source"`
	Destination string `yaml:"destination"`
}

type Service

type Service struct {
	Type         string  `yaml:"type"`
	Name         string  `yaml:"name"`
	Env          string  `yaml:"env"`
	BuildCommand string  `yaml:"buildCommand"`
	BuildPath    string  `yaml:"staticPublishPath"`
	Routes       []Route `yaml:"routes"`
}