modules

Documentation

Overview

This package implements interfaces to write modules for MIG.

For a guide on how to write modules, head over to http://mig.mozilla.org/doc/modules.rst.html

Index

• Variables
• func DefaultPersistHandlers(in io.ReadCloser, out io.WriteCloser, logch chan string, errch chan error, ...)
• func GetPersistListener(modname string) (l net.Listener, specname string, err error)
• func HandlePersistRequest(l net.Listener, f func(interface{}) string, errch chan error)
• func MakeMessage(class MessageClass, params interface{}, comp bool) (rawMsg []byte, err error)
• func MakeMessageLog(f string, args ...interface{}) (rawMsg []byte, err error)
• func MakeMessageRegister(spec string) (rawMsg []byte, err error)
• func ReadInputParameters(r io.Reader, p interface{}) (err error)
• func ReadPersistInputParameters(r io.Reader, p interface{}) (spath string, err error)
• func Register(name string, mod Moduler)
• func SendPersistRequest(p interface{}, sockspec string) (res string)
• func WatchForStop(r io.Reader, stopChan *chan bool) error
• func WriteOutput(buf []byte, w io.Writer) (err error)
• type HasEnhancedPrivacy
• type HasParamsCreator
• type HasParamsParser
• type HasResultsPrinter
• type LogParams
• type Message
  • func ReadInput(r io.Reader) (msg Message, err error)
• type MessageClass
• type Moduler
• type PersistRunner
• type RegParams
• type Result
  • func (r Result) GetElements(el interface{}) (err error)
  • func (r Result) GetStatistics(stats interface{}) (err error)
• type Runner

Variables

var Available = make(map[string]Moduler)

The set of registered modules

var ModuleRunDir string

Functions

func DefaultPersistHandlers

func DefaultPersistHandlers(in io.ReadCloser, out io.WriteCloser, logch chan string,
	errch chan error, regch chan string)

A general management function that can be called by persistent modules from the RunPersist function. Looks after replying to ping messages, writing logs, and other communication between the agent and the running persistent module.

func GetPersistListener

func GetPersistListener(modname string) (l net.Listener, specname string, err error)

Get a listener for a persistent module that is appropriate for the platform type, returns the listener itself in addition to the socket specification that should be registered.

func HandlePersistRequest

func HandlePersistRequest(l net.Listener, f func(interface{}) string, errch chan error)

Request handler that can be called from RunPersist in a persistent module. Looks after accepting incoming requests to listener l, and routing the requests to the registered incoming request handler f.

func MakeMessage

func MakeMessage(class MessageClass, params interface{}, comp bool) (rawMsg []byte, err error)

MakeMessage creates a new modules.Message with a given class and parameters and return the byte slice of the json marshalled message

func MakeMessageLog

func MakeMessageLog(f string, args ...interface{}) (rawMsg []byte, err error)

MakeMessageLog creates a new message of class log.

func MakeMessageRegister

func MakeMessageRegister(spec string) (rawMsg []byte, err error)

Creates a new message of class register.

func ReadInputParameters

func ReadInputParameters(r io.Reader, p interface{}) (err error)

ReadInputParameters reads the first line from stdin and expects to find a modules.Message of class `parameters`. This function uses ReadInput and will block waiting for data on stdin

func ReadPersistInputParameters

func ReadPersistInputParameters(r io.Reader, p interface{}) (spath string, err error)

ReadPersistInputParameters performs the same function as ReadInputParameters however it also validates a socket path has been specified to query the persistent module, returning an error if this is not present. Populates p and also returns the socket path.

func Register

func Register(name string, mod Moduler)

Register a new module as available

func SendPersistRequest

func SendPersistRequest(p interface{}, sockspec string) (res string)

Sends the parameters in p as a request to a persistent module listening at socket specification sockspec; would typically be used in the Run() function of a persistent module.

func WatchForStop

func WatchForStop(r io.Reader, stopChan *chan bool) error

WatchForStop continuously reads stdin for a stop message. When one is received, `true` is sent into the stop channel.

func WriteOutput

func WriteOutput(buf []byte, w io.Writer) (err error)

Write output in buf to writer w. buf is expected to contain a single line of data, and a line feed is appended to terminate the line as module IO is line delimited.

Types

type HasEnhancedPrivacy

type HasEnhancedPrivacy interface {
	EnhancePrivacy(Result) (Result, error)
}

type HasParamsCreator

type HasParamsCreator interface {
	ParamsCreator() (interface{}, error)
}

HasParamsCreator implements a function that creates module parameters

type HasParamsParser

type HasParamsParser interface {
	ParamsParser([]string) (interface{}, error)
}

HasParamsParser implements a function that parses command line parameters

type HasResultsPrinter

type HasResultsPrinter interface {
	PrintResults(Result, bool) ([]string, error)
}

HasResultsPrinter implements functions used by module to print information

type LogParams

type LogParams struct {
	Message string `json:"message"`
}

Parameter format expected for a log message

type Message

type Message struct {
	Class       MessageClass `json:"class"`                 // represent the type of message being passed to the module
	Parameters  interface{}  `json:"parameters,omitempty"`  // for `parameters` class, this interface contains the module parameters
	PersistSock string       `json:"persistsock,omitempty"` // Persistent module socket path if required
}

Message defines the input messages received by modules.

All messages will have Class and Parameters set. PersistSock is used in a case where a parameters message is being sent for a persistent module. In this case, PersistSock will contain the socket specification the module has registered as listening on.

func ReadInput

func ReadInput(r io.Reader) (msg Message, err error)

ReadInput reads one line of input from stdin, unmarshal it into a modules.Message and returns the message to the caller

type MessageClass

type MessageClass string

const (
	MsgClassParameters MessageClass = "parameters"
	MsgClassStop       MessageClass = "stop"
	MsgClassPing       MessageClass = "ping"
	MsgClassLog        MessageClass = "log"
	MsgClassRegister   MessageClass = "register"
)

type Moduler

type Moduler interface {
	NewRun() Runner
}

A mig module implements this interface

type PersistRunner

type PersistRunner interface {
	RunPersist(io.ReadCloser, io.WriteCloser)
}

PersistRunner provides the interface to execution of a persistent module. All modules will satisfy Runner. Persistent modules will satisfy both Runner and PersistRunner.

type RegParams

type RegParams struct {
	SockPath string `json:"sockpath"`
}

Parameter format expected for a register message

type Result

type Result struct {
	FoundAnything bool        `json:"foundanything"`
	Success       bool        `json:"success"`
	Elements      interface{} `json:"elements"`
	Statistics    interface{} `json:"statistics"`
	Errors        []string    `json:"errors"`
}

Result implement the base type for results returned by modules. All modules must return this type of result. The fields are:

• FoundAnything: a boolean that must be set to true if the module ran a search that returned at least one positive result

• Success: a boolean that must be set to true if the module ran without fatal errors. soft errors are reported in Errors

• Elements: an undefined type that can be customized by the module to contain the detailled results

• Statistics: an undefined type that can be customized by the module to contain some information about how it ran

• Errors: an array of strings that contain non-fatal errors encountered by the module

func (Result) GetElements

func (r Result) GetElements(el interface{}) (err error)

GetElements reads the elements from a struct of results into the el interface

func (Result) GetStatistics

func (r Result) GetStatistics(stats interface{}) (err error)

GetStatistics reads the statistics from a struct of results into the stats interface

type Runner

type Runner interface {
	Run(io.Reader) string
	ValidateParameters() error
}

Runner provides the interface to an execution of a module