slash

README

Slash

A framework for Slack slash commands with Go, inspired by net/http and hubot.

Example

package slash_test

import (
  "net/http"
  "regexp"

  "github.com/ejholmes/slash"
  "golang.org/x/net/context"
)

func Example() {
  r := slash.NewMux()
  r.Command("/weather", "secrettoken", slash.HandlerFunc(Weather))

  s := slash.NewServer(r)
  http.ListenAndServe(":8080", s)
}

// Weather is the primary slash handler for the /weather command.
func Weather(ctx context.Context, r slash.Responder, command slash.Command) (slash.Response, error) {
  h := slash.NewMux()

  var zipcodeRegex = regexp.MustCompile(`(?P<zip>[0-9])`)
  h.MatchText(zipcodeRegex, slash.HandlerFunc(Zipcode))

  return h.ServeCommand(ctx, r, command)
}

// Zipcode is a slash handler that returns the weather for a zip code.
func Zipcode(ctx context.Context, r slash.Responder, command slash.Command) (slash.Response, error) {
  params := slash.Params(ctx)
  zip := params["zip"]
  return slash.Reply(zip), nil
}

Documentation

Overview

Example

package main

import (
	"net/http"
	"regexp"

	"github.com/ejholmes/slash"
	"golang.org/x/net/context"
)

func main() {
	r := slash.NewMux()
	r.Command("/weather", "secrettoken", slash.HandlerFunc(Weather))

	s := slash.NewServer(r)
	http.ListenAndServe(":8080", s)
}

// Weather is the primary slash handler for the /weather command.
func Weather(ctx context.Context, r slash.Responder, command slash.Command) (slash.Response, error) {
	h := slash.NewMux()

	var zipcodeRegex = regexp.MustCompile(`(?P<zip>[0-9])`)
	h.MatchText(zipcodeRegex, slash.HandlerFunc(Zipcode))

	return h.ServeCommand(ctx, r, command)
}

// Zipcode is a slash handler that returns the weather for a zip code.
func Zipcode(ctx context.Context, r slash.Responder, command slash.Command) (slash.Response, error) {
	params := slash.Params(ctx)
	zip := params["zip"]
	return slash.Reply(zip), nil
}

Index

• Variables
• func Params(ctx context.Context) map[string]string
• func WithParams(ctx context.Context, params map[string]string) context.Context
• type Command
  • func CommandFromValues(v url.Values) (Command, error)
  • func ParseRequest(r *http.Request) (Command, error)
• type Handler
  • func ValidateToken(h Handler, token string) Handler
• type HandlerFunc
  • func (fn HandlerFunc) ServeCommand(ctx context.Context, r Responder, command Command) (Response, error)
• type Matcher
  • func MatchCommand(cmd string) Matcher
  • func MatchSubcommand(subcmd string) Matcher
  • func MatchTextRegexp(r *regexp.Regexp) Matcher
• type MatcherFunc
  • func (fn MatcherFunc) Match(command Command) (map[string]string, bool)
• type Mux
  • func NewMux() *Mux
  • func (m *Mux) Command(command, token string, handler Handler) *Route
  • func (m *Mux) Handler(command Command) (Handler, map[string]string)
  • func (m *Mux) Match(matcher Matcher, handler Handler) *Route
  • func (m *Mux) MatchText(re *regexp.Regexp, handler Handler) *Route
  • func (m *Mux) ServeCommand(ctx context.Context, r Responder, command Command) (Response, error)
• type Responder
• type Response
  • func Reply(text string) Response
  • func Say(text string) Response
• type Route
  • func NewRoute(handler Handler) *Route
• type Server
  • func NewServer(h Handler) *Server
  • func (h *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)

Examples

• Package

Variables

var (
	// ErrNoHandler is returned by Mux ServeCommand if a Handler isn't found
	// for the route.
	ErrNoHandler = errors.New("slash: no handler")

	// ErrInvalidToken is returned when the provided token in the request
	// does not match the expected secret.
	ErrInvalidToken = errors.New("slash: invalid token")
)

var NoResponse = Response{}

An empty response.

Functions

func Params

func Params(ctx context.Context) map[string]string

Params returns the match groups from a regular expression match.

func WithParams

func WithParams(ctx context.Context, params map[string]string) context.Context

Types

type Command

type Command struct {
	Token string

	TeamID     string
	TeamDomain string

	ChannelID   string
	ChannelName string

	UserID   string
	UserName string

	Command string
	Text    string

	ResponseURL *url.URL
}

Command represents an incoming Slash Command request.

func CommandFromValues

func CommandFromValues(v url.Values) (Command, error)

CommandFromValues returns a Command object from a url.Values object.

func ParseRequest

func ParseRequest(r *http.Request) (Command, error)

ParseRequest parses the form an then returns the extracted Command.

type Handler

type Handler interface {
	// ServeCommand runs the command. The handler should return a Response
	// that will be used as the initial reply to send back to the user, or
	// an error.  If an error is returned, then the string value is what
	// will be sent to the user.
	//
	// That provided Responder can be used to send asynchronous responses
	// after the initial response, up to 30 minutes after the command was
	// invoked.
	ServeCommand(context.Context, Responder, Command) (Response, error)
}

Handler represents something that handles a slash command.

func ValidateToken

func ValidateToken(h Handler, token string) Handler

ValidateToken returns a new Handler that verifies that the token in the request matches the given token.

type HandlerFunc

type HandlerFunc func(context.Context, Responder, Command) (Response, error)

HandlerFunc is a function that implements the Handler interface.

func (HandlerFunc) ServeCommand

func (fn HandlerFunc) ServeCommand(ctx context.Context, r Responder, command Command) (Response, error)

type Matcher

type Matcher interface {
	Match(Command) (map[string]string, bool)
}

Matcher is something that can check if a Command matches a Route.

func MatchCommand

func MatchCommand(cmd string) Matcher

MatchCommand returns a Matcher that checks that the command strings match.

func MatchSubcommand

func MatchSubcommand(subcmd string) Matcher

MatchSubcommand returns a Matcher that checks for the first string of the text portion of a command, assuming it's a subcommand.

func MatchTextRegexp

func MatchTextRegexp(r *regexp.Regexp) Matcher

MatchTextRegexp returns a Matcher that checks that the command text matches a regular expression.

type MatcherFunc

type MatcherFunc func(Command) (map[string]string, bool)

MatcherFunc is a function that implements Matcher.

func (MatcherFunc) Match

func (fn MatcherFunc) Match(command Command) (map[string]string, bool)

type Mux

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

Mux is a Handler implementation that routes commands to Handlers.

func NewMux

func NewMux() *Mux

NewMux returns a new Mux instance.

func (*Mux) Command

func (m *Mux) Command(command, token string, handler Handler) *Route

Handle adds a Handler to handle the given command.

Example

m.Handle("/deploy", "token", DeployHandler)

func (*Mux) Handler

func (m *Mux) Handler(command Command) (Handler, map[string]string)

Handler returns the Handler that can handle the given slash command. If no handler matches, nil is returned.

func (*Mux) Match

func (m *Mux) Match(matcher Matcher, handler Handler) *Route

Match adds a new route that uses the given Matcher to match.

func (*Mux) MatchText

func (m *Mux) MatchText(re *regexp.Regexp, handler Handler) *Route

MatchText adds a route that matches when the text of the command matches the given regular expression. If the route matches and is called, slash.Matches will return the capture groups.

func (*Mux) ServeCommand

func (m *Mux) ServeCommand(ctx context.Context, r Responder, command Command) (Response, error)

ServeCommand attempts to find a Handler to serve the Command. If no handler is found, an error is returned.

type Responder

type Responder interface {
	Respond(Response) error
}

Responder represents an object that can send Responses.

type Response

type Response struct {
	InChannel bool
	Text      string
}

Response represents the response to send back to the user.

func Reply

func Reply(text string) Response

Reply returns a Response object that will reply to the user silently with an "ephmeral" message.

func Say

func Say(text string) Response

Say returns a Response object that will post to the channel publicly.

type Route

type Route struct {
	Handler
	Matcher
}

Route wraps a Handler with a Matcher.

func NewRoute

func NewRoute(handler Handler) *Route

NewRoute returns a new Route instance.

type Server

type Server struct {
	Handler
}

Server adapts a Handler to be served over http.

func NewServer

func NewServer(h Handler) *Server

NewServer returns a new Server instance.

func (*Server) ServeHTTP

func (h *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP parses the Command from the incoming request then serves it using the Handler.