notifier

README

notifier

The noteserver is a program that runs on a local macOS machine and exposes various useful endpoints via JSON-RPC 2.0. Combined with SSH forwarding, it can be used to integrate notifications, clipboard, and other useful bits with a terminal session on a remote system.

Warning: This is by no means a polished product; this is just something I find useful and have tweaked as needed to make things work.

Documentation

Overview

Package notifier contains common data structures for notifications.

Index

• Variables
• func Columns(w io.Writer, write func(io.Writer))
• func Dial(ctx context.Context) (context.Context, *jrpc2.Client, error)
• func LoadConfig(path string, cfg *Config) error
• func NoteLess(a, b *Note) bool
• func PluginAssigner(cfg *Config) jrpc2.Assigner
• func PromptForText(ctx context.Context, req *TextRequest) (string, error)
• func RegisterFlags()
• func RegisterPlugin(name string, p Plugin)
• func SetSystemClipboard(ctx context.Context, data []byte) error
• type ClipClearRequest
• type ClipGetRequest
• type ClipSetRequest
• type Config
  • func (c *Config) EditFile(ctx context.Context, path string) error
  • func (c *Config) EditFileCmd(ctx context.Context, path string) (*exec.Cmd, error)
• type EditNotesRequest
• type EditRequest
• type KeyGenReply
• type KeyGenRequest
• type ListNotesRequest
• type Note
• type NoteCategory
  • func (c *NoteCategory) FilePath(base, version, ext string) string
• type NoteWithText
• type Plugin
• type PostRequest
• type SayRequest
• type SiteRequest
• type TextRequest

Variables

var ErrNotApplicable = errors.New("plugin is not applicable")

ErrNotApplicable is returned by a plugin's Init function if the plugin cannot be used with the given configuration.

var ResourceNotFound = code.Register(-29998, "resource not found")

ResourceNotFound is returned when a requested resource is not found.

var UserCancelled = code.Register(-29999, "user cancelled request")

UserCancelled is the code returned when a user cancels a text request.

Functions

func Columns

func Columns(w io.Writer, write func(io.Writer))

Columns calls write with a tabwriter directed to w, and flushes its output when write returns.

func Dial

func Dial(ctx context.Context) (context.Context, *jrpc2.Client, error)

Dial connects to the flag-selected JSON-RPC server and returns a context and a client ready for use. The caller is responsible for closing the client.

func LoadConfig

func LoadConfig(path string, cfg *Config) error

LoadConfig loads a configuration from the file at path into *cfg.

func NoteLess

func NoteLess(a, b *Note) bool

NoteLess reports whether a should be ordered prior to b, first by tag and then by version.

func PluginAssigner

func PluginAssigner(cfg *Config) jrpc2.Assigner

PluginAssigner returns a jrpc2.Assigner that exports the methods of all the registered plugins.

func PromptForText

func PromptForText(ctx context.Context, req *TextRequest) (string, error)

PromptForText requests a string of text from the user.

func RegisterFlags

func RegisterFlags()

RegisterFlags installs a standard -server flag in the default flagset. This function should be called during init in a client main package.

func RegisterPlugin

func RegisterPlugin(name string, p Plugin)

RegisterPlugin registers a plugin. This function will panic if the same name is registered multiple times.

func SetSystemClipboard

func SetSystemClipboard(ctx context.Context, data []byte) error

SetSystemClipboard sets the contents of the system clipboard to data.

Types

type ClipClearRequest

type ClipClearRequest struct {
	Tag string `json:"tag,omitempty"` // the tag to clear or remove
}

A ClipClearRequest is sent to clear the contents of the clipboard.

type ClipGetRequest

type ClipGetRequest struct {
	Tag      string `json:"tag,omitempty"`      // the tag to assign the data
	Save     string `json:"save,omitempty"`     // save active clip to this tag
	Activate bool   `json:"activate,omitempty"` // make this clip active
}

A ClipGetRequest is sent to query the contents of the clipboard.

type ClipSetRequest

type ClipSetRequest struct {
	Data       []byte `json:"data"`           // the data to be stored
	Tag        string `json:"tag,omitempty"`  // the tag to assign the data
	Save       string `json:"save,omitempty"` // save active clip to this tag
	AllowEmpty bool   `json:"allowEmpty"`     // allow data to be empty
}

A ClipSetRequest is sent to update the contents of the clipboard.

type Config

type Config struct {
	Address  string
	DebugLog bool `yaml:"debugLog"`

	// Settings for the clipboard service.
	Clip struct {
		SaveFile string `yaml:"saveFile"`
	}

	// Settings for the editor service.
	Edit struct {
		Command  string
		TouchNew bool `yaml:"touchNew"`
	}

	// Settings for the notes service.
	Notes struct {
		Categories []*NoteCategory
	}

	// Settings for the key generation service.
	Key struct {
		ConfigFile string `yaml:"configFile"`
	}

	// Settings for the notification service.
	Notify struct {
		Sound string
		Voice string
	}
}

Config stores settings for the various notifier services.

func (*Config) EditFile

func (c *Config) EditFile(ctx context.Context, path string) error

EditFile edits a file using the editor specified by c.

func (*Config) EditFileCmd

func (c *Config) EditFileCmd(ctx context.Context, path string) (*exec.Cmd, error)

EditFileCmd returns a command to edit the specified file using the editor specified by c. The caller must run or start the command.

type EditNotesRequest

type EditNotesRequest struct {
	// The name tag of the notes file to edit.
	Tag string `json:"tag,omitempty"`

	// An optional note category, e.g., "meetings".
	Category string `json:"category,omitempty"`

	// Which version of the notes to edit. If it is "new", a new version is
	// created for this base name.  If it is "" or "latest", the latest
	// matching version for this base name is edited.  Otherwise, this must be
	// a date in YYYY-MM-DD format.
	Version string `json:"version,omitempty"`

	// If true, return as soon as the editor starts rather than waiting for it
	// to terminate.
	Background bool `json:"background,omitempty"`
}

An EditNotesRequest is a request to edit the contents of a notes file.

type EditRequest

type EditRequest struct {
	// The base name of the file to edit.
	Name string `json:"name,omitempty"`

	// The current contents of the file.
	Content []byte `json:"content,omitempty"`
}

An EditRequest is a request to edit the contents of a file.

type KeyGenReply

type KeyGenReply struct {
	// If the key was copied, the "key" field will be omitted.
	Key   string `json:"key,omitempty"`
	Hash  string `json:"hash"`
	Label string `json:"label"`
}

A KeyGenReply is the response from the key generator.

type KeyGenRequest

type KeyGenRequest struct {
	Host   string  `json:"host,omitempty"`   // host or site label
	Strict bool    `json:"strict,omitempty"` // report error if label is not known
	Copy   bool    `json:"copy,omitempty"`   // copy to clipboard
	Format *string `json:"format,omitempty"` // render using this format
	Length *int    `json:"length,omitempty"` // generated passphrase length
	Punct  *bool   `json:"punct,omitempty"`  // use punctuation in passphrases
	Salt   *string `json:"salt,omitempty"`   // salt for passphrase generation
}

A KeyGenRequest is a request to generate a password.

type ListNotesRequest

type ListNotesRequest struct {
	// List files matching this name tag (match all, if empty)
	Tag string `json:"tag,omitempty"`

	// List files in this note category, e.g., "meetings".  If empty, list files
	// in all categories.
	Category string `json:"category,omitempty"`

	// List files matching this version (globs OK, e.g., "2018-11-*").
	Version string `json:"version,omitempty"`
}

A ListNotesRequest is a request to list the available notes.

type Note

type Note struct {
	Tag      string `json:"tag,omitempty"`
	Version  string `json:"version,omitempty"`
	Suffix   string `json:"suffix,omitempty"`
	Category string `json:"category,omitempty"`
	Path     string `json:"path,omitempty"`
}

A Note describes an editable note.

type NoteCategory

type NoteCategory struct {
	Name   string `json:"name"`             // the name of the category
	Dir    string `json:"dir"`              // the direcory where notes are stored
	Suffix string `json:"suffix,omitempty"` // the default file suffix for this category
}

A NoteCategory describes the configuration settings for a notes category.

func (*NoteCategory) FilePath

func (c *NoteCategory) FilePath(base, version, ext string) string

FilePath constructs a filepath for the specified base, version, and extension relative to the directory of the specified category.

type NoteWithText

type NoteWithText struct {
	*Note
	Text []byte `json:"text"`
}

A NoteWithText reports a note and its content.

type Plugin

type Plugin interface {
	// Init is called once before any other methods of the plugin are used, with
	// a pointer to the shared configuration.
	Init(*Config) error

	// Update may be called periodically to give the plugin an opportunity to
	// update its state.
	Update() error

	// Assigner returns an assigner for handlers.
	Assigner() jrpc2.Assigner
}

A Plugin exposes a set of methods.

type PostRequest

type PostRequest struct {
	Title    string        `json:"title,omitempty"`
	Subtitle string        `json:"subtitle,omitempty"`
	Body     string        `json:"body,omitempty"`
	Audible  bool          `json:"audible,omitempty"`
	After    time.Duration `json:"after,omitempty"`
}

A PostRequest is a request to post a notification to the user.

type SayRequest

type SayRequest struct {
	Text  string        `json:"text"`
	Voice string        `json:"voice,omitempty"`
	After time.Duration `json:"after,omitempty"`
}

A SayRequest is a request to speak a notification to the user.

type SiteRequest

type SiteRequest struct {
	Host   string `json:"host,omitempty"`
	Strict bool   `json:"strict,omitempty"`
	Full   bool   `json:"full,omitempty"`
}

A SiteRequest is a request for site data.

type TextRequest

type TextRequest struct {
	Prompt  string `json:"prompt,omitempty"`
	Default string `json:"default,omitempty"`
	Hide    bool   `json:"hide,omitempty"`
}

A TextRequest is a request to read a string from the user.