service

Documentation

Overview

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

Overview

service aims to present a way to write canonical services, which behave correctly in all instances.

Index

• func UserConfDir() (string, error)
• func UserShareDir() (string, error)
• type ComGroup
• type Command
  • func FindCommands(b []byte) ([]*Command, error)
  • func FromString(cmd string) (*Command, error)
  • func (c *Command) Bytes() []byte
  • func (c *Command) String() string
• type Control
  • func New(ctl interface{}, store store.Filer, listener listener.Listener, logdir string, ...) (*Control, error)
  • func (c *Control) Cleanup()
  • func (c *Control) Context() context.Context
  • func (c *Control) CreateBuffer(name string) error
  • func (c *Control) DeleteBuffer(name string) error
  • func (c *Control) ErrorWriter() (*control.WriteCloser, error)
  • func (c *Control) HasBuffer(name string) bool
  • func (c *Control) ImageWriter(buffer, resource string) (*control.WriteCloser, error)
  • func (c *Control) Listen() error
  • func (c *Control) MainWriter(buffer string) (*control.WriteCloser, error)
  • func (c *Control) NavWriter(buffer string) (*control.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) (*control.WriteCloser, error)
  • func (c *Control) StatusWriter(buffer string) (*control.WriteCloser, error)
  • func (c *Control) TitleWriter(buffer string) (*control.WriteCloser, error)
• type Manager

Examples

• Control.Listen

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 FromString

func FromString(cmd string) (*Command, error)

FromString returns a partially filled command It will have a Heading type of DefaultGroup

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 {
	// contains filtered or unexported fields
}

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

func New

func New(ctl interface{}, store store.Filer, listener listener.Listener, logdir string, debug bool) (*Control, error)

New sets up a ready-to-listen ctl file logdir is the directory to store the contents written to the main element of a buffer. Logging any other type of data is left to implementation details, but is considered poor form for Altid's design. This will return an error if a ctl file exists at the given directory

func (*Control) Cleanup

func (c *Control) Cleanup()

Cleanup flushes anything pending to logs, and disconnects any remaining clients

func (*Control) Context

func (c *Control) Context() context.Context

Context returns the underlying context of the service This will be closed after Quit() is called

func (*Control) CreateBuffer

func (c *Control) CreateBuffer(name 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))` 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 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() (*control.WriteCloser, error)

ErrorWriter returns a WriteCloser attached to a services' errors file

func (*Control) HasBuffer

func (c *Control) HasBuffer(name 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) (*control.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 starts a network listener for incoming clients

Example

package main

import (
	"log"

	"github.com/altid/libs/service"
	"github.com/altid/libs/service/listener"
	"github.com/altid/libs/store"
)

type Manager struct{}

func (m *Manager) Run(*service.Command, *service.Control) error {
	// Callback - do something with a given command
	// [...]
	return nil
}

func (m *Manager) Quit() {
	// Clean up any state here
	// [...]
}

func main() {
	// Register everything we use to the service controller
	listen, err := listener.NewListen9p("127.0.0.1", "", "")
	if err != nil {
		log.Fatal(err)
	}

	s := store.NewRamStore()
	manage := Manager{}

	ctl, err := service.New(manage, s, listen, "", false)
	if err != nil {
		log.Fatal(err)
	}

	// Before we can call ctl.Listen, we need to register a store for our listener
	// Not doing this will return an error
	if e := listen.Register(s, nil); e != nil {
		log.Fatal(e)
	}

	// Finally call our embedded listener
	ctl.Listen()
}

func (*Control) MainWriter

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

MainWriter returns a WriteCloser attached to a buffer's main output

func (*Control) NavWriter

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

NavWriter returns a WriteCloser attached to a buffers nav 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) (*control.WriteCloser, error)

SideWriter returns a WriteCloser attached to a buffers `aside` file

func (*Control) StatusWriter

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

StatusWriter returns a WriteCloser attached to a buffers status file

func (*Control) TitleWriter

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

TitleWriter returns a WriteCloser attached to a buffers title file

type Manager

type Manager interface {
	Run(*Control, *Command) error
	Quit()
}