fs

Documentation

Overview

Package fs is a library which allows you to write well constructed Altid services

Overview

fs aims to present a way to write canonical services, which behave correctly in all instances. A service in Altid has the following structure on disk:

/
	ctl
	events
	errors
	buffer1/
	buffer2/
	[...]

All buffer management occurs through writes to the ctl file. To open a buffer, for example, you write

open mybuffer > /path/to/service/ctl

This in turn calls the Open function of a Handler, as described below.

Any errors encountered in the lifetime of a service will be logged to `errors`, and any events on any buffers will be logged to `events`

Index

• func UserConfDir() (string, error)
• func UserShareDir() (string, error)
• type ComGroup
• type Command
  • func FindCommands(b []byte) ([]*Command, error)
  • func (c *Command) Bytes() []byte
  • func (c *Command) String() string
• type Control
  • func CreateCtlFile(ctx context.Context, ctl Controller, logdir, mtpt, service, doctype string, ...) (*Control, error)
  • func MockCtlFile(ctx context.Context, ctl Controller, reqs chan string, service string, ...) (*Control, error)
  • func (c *Control) Cleanup()
  • func (c *Control) CreateBuffer(name, doctype string) error
  • func (c *Control) DeleteBuffer(name, doctype string) error
  • func (c *Control) ErrorWriter() (*writer.WriteCloser, error)
  • func (c *Control) Event(eventmsg string) error
  • func (c *Control) HasBuffer(name, doctype string) bool
  • func (c *Control) ImageWriter(buffer, resource string) (*writer.WriteCloser, error)
  • func (c *Control) Listen() error
  • func (c *Control) MainWriter(buffer, doctype string) (*writer.WriteCloser, error)
  • func (c *Control) NavWriter(buffer string) (*writer.WriteCloser, error)
  • func (c *Control) Notification(buff, from, msg string) error
  • func (c *Control) Remove(buffer, filename string) error
  • func (c *Control) SetCommands(cmd ...*Command) error
  • func (c *Control) SideWriter(buffer string) (*writer.WriteCloser, error)
  • func (c *Control) StatusWriter(buffer string) (*writer.WriteCloser, error)
  • func (c *Control) TitleWriter(buffer string) (*writer.WriteCloser, error)
• type Controller
• type Handler
• type Input
  • func NewInput(h Handler, dir, buffer string, debug bool) (*Input, error)
  • func NewMockInput(h Handler, buffer string, debug bool, reqs chan string) (*Input, error)
  • func (i *Input) Errs() []error
  • func (i *Input) Start()
  • func (i *Input) StartContext(ctx context.Context)
  • func (i *Input) Stop()

Functions

func UserConfDir

func UserConfDir() (string, error)

UserConfDir returns the default root directory to use for user-specific configuration data. Users should create their own application-specific subdirectory within this one and use that. On Unix systems, it returns $XDG_CONFIG_HOME as specified by https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html if non-empty, else $HOME/.config. On Darwin, it returns $HOME/Library/Preferences. On Windows, it returns %LocalAppData%. On Plan 9, it returns $home/lib.

func UserShareDir

func UserShareDir() (string, error)

UserShareDir returns the default root directory to use for user-specific application data. Users should create their own application-specific subdirectory within this one and use that. On Unix systems, it returns $XDG_DATA_HOME as specified by https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html if non-empty, else $HOME/.local/share. On Darwin, it returns $HOME/Library. On Windows, it returns %LocalAppData%. On Plan 9, it returns $home/lib.

Types

type ComGroup

type ComGroup int

ComGroup is a logical grouping of commands To add a ComGroup, please do so in a PR

const (
	DefaultGroup ComGroup = iota
	ActionGroup
	MediaGroup
	ServiceGroup
)

Currently supported ComGroups

type Command

type Command struct {
	Name        string
	Description string
	Heading     ComGroup
	Args        []string
	Alias       []string
	From        string
}

Command represents an available command to a service The From field should generally be populated, except in the case of a ServiceGroup command

func FindCommands

func FindCommands(b []byte) ([]*Command, error)

FindCommands within a byte array It returns an error if it encounters malformed input

func (*Command) Bytes

func (c *Command) Bytes() []byte

Bytes - Return a byte representation of a command

func (*Command) String

func (c *Command) String() string

type Control

type Control struct {
	sync.Mutex
	// contains filtered or unexported fields
}

Control type can be used to manage a running ctl file session

func CreateCtlFile

func CreateCtlFile(ctx context.Context, ctl Controller, logdir, mtpt, service, doctype string, debug bool) (*Control, error)

CreateCtlFile sets up a ready-to-listen ctl file logdir is the directory to store copies of the contents of files created; specifically doctype. Logging any other type of data is left to implementation details, but is considered poor form for Altid's design. mtpt is the directory to create the file system in service is the subdirectory inside mtpt for the runtime fs This will return an error if a ctl file exists at the given directory, or if doctype is invalid.

func MockCtlFile

func MockCtlFile(ctx context.Context, ctl Controller, reqs chan string, service string, debug bool) (*Control, error)

MockCtlFile returns a type that can be used for testing services it will track in-memory and behave like a file-backed control It will wait for messages on reqs which act as ctl messages By default it writes to Stdout + Stderr with each WriteCloser If debug is true, all logs will be written to stdout

func (*Control) Cleanup

func (c *Control) Cleanup()

Cleanup removes created symlinks and removes the main dir On plan9, it unbinds any file named "document" or "feed", prior to removing the directory itself.

func (*Control) CreateBuffer

func (c *Control) CreateBuffer(name, doctype string) error

CreateBuffer creates a buffer of given name, as well as symlinking your file as follows: `os.Symlink(path.Join(logdir, name), path.Join(rundir, name, doctype))` This logged file will persist across reboots Calling CreateBuffer on a directory that already exists will return nil

func (*Control) DeleteBuffer

func (c *Control) DeleteBuffer(name, doctype string) error

DeleteBuffer unlinks a document/buffer, and cleanly removes the directory Will return an error if it's unable to unlink on plan9, or if the remove fails.

func (*Control) ErrorWriter

func (c *Control) ErrorWriter() (*writer.WriteCloser, error)

ErrorWriter returns a WriteCloser attached to a services' errors file

func (*Control) Event

func (c *Control) Event(eventmsg string) error

Event appends the given string to the events file of Control's working directory. Strings cannot contain newlines, tabs, spaces, or control characters. Returns "$service: invalid event $eventmsg" or nil.

func (*Control) HasBuffer

func (c *Control) HasBuffer(name, doctype string) bool

HasBuffer returns whether or not a buffer is present in the current control session

func (*Control) ImageWriter

func (c *Control) ImageWriter(buffer, resource string) (*writer.WriteCloser, error)

ImageWriter returns a WriteCloser attached to a named file in the buffers' image directory

func (*Control) Listen

func (c *Control) Listen() error

Listen creates a file named "ctl" inside RunDirectory, after making sure the directory exists Any text written to the ctl file will be parsed, line by line. Messages handled internally are as follows: open (or join), close (or part), and quit, which causes Listen() to return. This will return an error if we're unable to create the ctlfile itself, and will log any error relating to control messages.

func (*Control) MainWriter

func (c *Control) MainWriter(buffer, doctype string) (*writer.WriteCloser, error)

MainWriter returns a WriteCloser attached to a buffers feed/document function to set the contents of a given buffers' document or feed file, which will as well send the correct event to the events file

func (*Control) NavWriter

func (c *Control) NavWriter(buffer string) (*writer.WriteCloser, error)

NavWriter returns a WriteCloser attached to a buffers nav file, which will as well send the correct event to the events file

func (*Control) Notification

func (c *Control) Notification(buff, from, msg string) error

Notification appends the content of msg to a buffers notification file Any errors encountered during file opening/creation will be returned The canonical form of notification can be found in the markup libs' Notification type, And the output of the Parse() method can be used directly here For example

ntfy, err := markup.NewNotifier(buff, from, msg)
if err != nil {
    log.Fatal(err)
}
fs.Notification(ntfy.Parse())

func (*Control) Remove

func (c *Control) Remove(buffer, filename string) error

Remove removes a buffer from the runtime dir. If the buffer doesn't exist, this is a no-op

func (*Control) SetCommands

func (c *Control) SetCommands(cmd ...*Command) error

SetCommands allows services to add additional commands Any client command encountered which matches will send The resulting command down to RunCommand Commands must include at least a name and a heading Running SetCommands after calling Start or Listen will have no effect

func (*Control) SideWriter

func (c *Control) SideWriter(buffer string) (*writer.WriteCloser, error)

SideWriter returns a WriteCloser attached to a buffers `aside` file, which will as well send the correct event to the events file

func (*Control) StatusWriter

func (c *Control) StatusWriter(buffer string) (*writer.WriteCloser, error)

StatusWriter returns a WriteCloser attached to a buffers status file, which will as well send the correct event to the events file

func (*Control) TitleWriter

func (c *Control) TitleWriter(buffer string) (*writer.WriteCloser, error)

TitleWriter returns a WriteCloser attached to a buffers title file, which will as well send the correct event to the events file

type Controller

type Controller interface {
	Open(c *Control, msg string) error
	Close(c *Control, msg string) error
	Link(c *Control, from, msg string) error
	Default(c *Control, cmd *Command) error
	Restart(c *Control) error
	Refresh(c *Control) error
	Quit()
}

Controller is our main type for controlling a session Open is called when a control message starting with 'open' or 'join' is written to the ctl file Close is called when a control message starting with 'close or 'part' is written to the ctl file Link is called when a control message starting with 'link' is written to the ctl file Default is called when any other control message is written to the ctl file. If a client attempts to write an invalid control message, it will return a generic error When Open is called, a file will be created with a path of `mountpoint/msg/document (or feed)`, containing initially a file named what you've set doctype to.. Calls to open are expected to populate that file, as well as create any supplementary files needed, such as title, aside, status, input, etc When Link is called, the content of the current buffer is expected to change, and the name of the current tab will be removed, replaced with msg The main document or feed file is also symlinked into the given log directory, under service/msgs, so for example, an expensive parse would only have to be completed once for a given request, even across separate runs; or a chat log could have history from previous sessions accessible. The message provided to all three functions is all of the message, less 'open', 'join', 'close', or 'part'.

type Handler

type Handler interface {
	Handle(path string, c *markup.Lexer) error
}

Handler is called whenever content is written to the associated `input` file

type Input

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

Input allows an Altid service to listen for writes to a file named input for a given buffer

func NewInput

func NewInput(h Handler, dir, buffer string, debug bool) (*Input, error)

NewInput takes a Handler and the name of a buffer. This function returns an Input, or nil as well as any errors encountered If debug is true, it will write to stdout for all messages/errors received

func NewMockInput

func NewMockInput(h Handler, buffer string, debug bool, reqs chan string) (*Input, error)

NewMockInput returns a faked input file for testing All writes to `reqs` will trigger the Handler internally

func (*Input) Errs

func (i *Input) Errs() []error

Errs returns a list of any errors encountered during input's runtime

func (*Input) Start

func (i *Input) Start()

Start will watch for reads on Input's path, and send messages to the callers Handle function Errors will be logged to the errors file

func (*Input) StartContext

func (i *Input) StartContext(ctx context.Context)

StartContext is a variant of Start which takes a context for cancellation

func (*Input) Stop

func (i *Input) Stop()

Stop ends the Input session, cleaning up after itself