import "git.sr.ht/~migadu/alps"
discover.go imap.go plugin.go plugin_go.go renderer.go server.go session.go smtp.go store.go
const PluginDir = "plugins"PluginDir is the path to the plugins directory.
var (
ErrSessionExpired = errors.New("session expired")
ErrAttachmentCacheSize = errors.New("Attachments on session exceed maximum file size")
)ErrNoStoreEntry is returned by Store.Get when the entry doesn't exist.
func RegisterPluginLoader(f PluginLoaderFunc)
RegisterPluginLoader registers a plugin loader. The loader will be called on server start-up and reload.
type Attachment struct {
File *multipart.FileHeader
Form *multipart.Form
}type AuthError struct {
// contains filtered or unexported fields
}AuthError wraps an authentication error.
type BaseRenderData struct {
GlobalData GlobalRenderData
// additional plugin-specific data
Extra map[string]interface{}
}BaseRenderData is the base type for templates. It should be extended with additional template-specific fields:
type MyRenderData struct {
BaseRenderData
// add additional fields here
}
func NewBaseRenderData(ectx echo.Context) *BaseRenderData
NewBaseRenderData initializes a new BaseRenderData.
It can be used by routes to pre-fill the base data:
type MyRenderData struct {
BaseRenderData
// add additional fields here
}
data := &MyRenderData{
BaseRenderData: *alps.NewBaseRenderData(ctx),
// other fields...
}
func (brd *BaseRenderData) Global() *GlobalRenderData
Global implements RenderData.
func (brd *BaseRenderData) WithTitle(title string) *BaseRenderData
type Context struct {
echo.Context
Server *Server
Session *Session // nil if user isn't logged in
}Context is the context used by HTTP handlers.
Use a type assertion to get it from a echo.Context:
ctx := ectx.(*alps.Context)
SetSession sets a cookie for the provided session. Passing a nil session unsets the cookie.
type DialIMAPFunc func() (*imapclient.Client, error)
DialIMAPFunc connects to the upstream IMAP server.
DialSMTPFunc connects to the upstream SMTP server.
type GlobalRenderData struct {
Path []string
URL *url.URL
LoggedIn bool
// if logged in
Username string
Title string
HavePlugin func(name string) bool
Notice string
// additional plugin-specific data
Extra map[string]interface{}
}GlobalRenderData contains data available in all templates.
GoPlugin is a helper to create Go plugins.
Use this struct to define your plugin, then call RegisterPluginLoader:
p := GoPlugin{Name: "my-plugin"}
// Define routes, template functions, etc
alps.RegisterPluginLoader(p.Loader())
func (p *GoPlugin) AddRoute(method, path string, handler HandlerFunc)
AddRoute registers a new HTTP route.
func (p *GoPlugin) DELETE(path string, handler HandlerFunc)
func (p *GoPlugin) GET(path string, handler HandlerFunc)
func (p *GoPlugin) Inject(name string, f InjectFunc)
Inject registers a function to execute prior to rendering a template. The special name "*" matches any template.
func (p *GoPlugin) Loader() PluginLoaderFunc
Loader returns a loader function for this plugin.
func (p *GoPlugin) POST(path string, handler HandlerFunc)
func (p *GoPlugin) PUT(path string, handler HandlerFunc)
Plugin returns an object implementing Plugin.
TemplateFuncs registers new template functions.
HandlerFunc is a function serving HTTP requests.
type InjectFunc func(ctx *Context, data RenderData) error
InjectFunc is a function that injects data prior to rendering a template.
type NoUpstreamError struct {
// contains filtered or unexported fields
}func (err *NoUpstreamError) Error() string
type Plugin interface {
// Name should return the plugin name.
Name() string
// LoadTemplate populates t with the plugin's functions and templates.
LoadTemplate(t *template.Template) error
// SetRoutes populates group with the plugin's routes.
SetRoutes(group *echo.Group)
// Inject is called prior to rendering a template. It can extend the
// template data by setting new items in the Extra map.
Inject(ctx *Context, name string, data RenderData) error
// Close is called when the plugin is unloaded.
Close() error
}Plugin extends alps with additional functionality.
PluginLoaderFunc loads plugins for the provided server.
type RenderData interface {
// GlobalData returns a pointer to the global render data.
Global() *GlobalRenderData
}RenderData is implemented by template data structs. It can be used to inject additional data to all templates.
type Server struct {
Sessions *SessionManager
Options *Options
// contains filtered or unexported fields
}Server holds all the alps server state.
New creates a new server.
Logger returns this server's logger.
Reload loads Lua plugins and templates from disk.
Upstream retrieves the configured upstream server URL for the provided schemes. If no configured upstream server matches, a *NoUpstreamError is returned. An empty URL.Scheme means that the caller needs to perform auto-discovery with URL.Host.
type Session struct {
// contains filtered or unexported fields
}Session is an active user session. It may also hold an IMAP connection.
The session's password is not available to plugins. Plugins should use the session helpers to authenticate outgoing connections, for instance DoSMTP.
Close destroys the session. This can be used to log the user out.
DoIMAP executes an IMAP operation on this session. The IMAP client can only be used from inside f.
DoSMTP executes an SMTP operation on this session. The SMTP client can only be used from inside f.
func (s *Session) PopAttachment(uuid string) *Attachment
Removes an attachment from the session. Returns nil if there was no such attachment.
Puts an attachment and returns a generated UUID
SetHTTPBasicAuth adds an Authorization header field to the request with this session's credentials.
Store returns a store suitable for storing persistent user data.
Username returns the session's username.
type SessionManager struct {
// contains filtered or unexported fields
}SessionManager keeps track of active sessions. It connects and re-connects to the upstream IMAP server as necessary. It prunes expired sessions.
func (sm *SessionManager) Close()
func (sm *SessionManager) Put(username, password string) (*Session, error)
Put connects to the IMAP server and creates a new session. If authentication fails, the error will be of type AuthError.
type Store interface {
Get(key string, out interface{}) error
Put(key string, v interface{}) error
}Store allows storing per-user persistent data.
Store shouldn't be used from inside Session.DoIMAP.
Package alps imports 28 packages (graph). Updated 2020-11-25. Refresh now. Tools for package owners.