README
¶
Diatheke Command Server
This package provides a simple http server that may be used for Diatheke command fulfillment. Such a server should be deployed with Diatheke, Cubic, Luna, etc. so that the Diatheke server can access the command server.
Security
Note that this server only supports http at the present. It does not allow secure connections (https), so any data sent to this server will not be encrypted. As such, it is not recommended to use this server for production.
Usage
Import the package using the go tool:
go get -u github.com/cobaltspeech/examples-go/cmdserver
To use the command server, create a new server, register command handlers and run.
type SomeHandler struct {
// Contains some data fields
}
func (h *SomeHandler) fooCmd(
in cmdserver.Input, out *cmdserver.Output) error {
// Do something interesting with the command input.
return nil
}
func (h *SomeHandler) barCmd(
in cmdserver.Input, out *cmdserver.Output) error {
// Do something interesting with the command input.
// Set output parameters
out.Parameters["expectedKey"] = "expectedVal"
return nil
}
func main() {
// Create the server (with an optional logger if desired)
svr := cmdserver.NewServer(nil)
// Set handlers for command IDs
handler := SomeHandler{}
svr.SetCommand("foo", handler.fooCmd)
svr.SetCommand("bar", handler.barCmd)
// It is also possible to set handlers based on model ID
// or model ID + command ID.
// svr.SetModel("modelID", handlerFunc)
// svr.SetModelCommand("modelID", "cmdID", handlerFunc)
// Run the server
if err := svr.Run(":24601"); err != nil {
os.Exit(1)
}
}
Documentation
¶
Index ¶
- type Handler
- type Input
- type Output
- type Params
- func (p Params) AsBool(key string) (bool, error)
- func (p Params) AsFloat32(key string) (float32, error)
- func (p Params) AsFloat64(key string) (float64, error)
- func (p Params) AsInt(key string) (int, error)
- func (p Params) AsString(key string) (string, error)
- func (p Params) SetBool(key string, val bool)
- func (p Params) SetFloat32(key string, val float32)
- func (p Params) SetFloat64(key string, val float64)
- func (p Params) SetInt(key string, val int)
- func (p Params) SetString(key, val string)
- type Server
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Handler ¶
Handler is a function that takes command input and sets the command output that is expected by a Diatheke command.
type Input ¶ added in v1.1.0
type Input struct {
// The Diatheke model ID where the command is defined.
ModelID string `json:"modelID"`
// The ID of the command to execute.
CommandID string `json:"id"`
// The unique ID of the session trying to execute the command.
SessionID string `json:"sessionID"`
// Defined parameters (possibly empty).
Parameters Params `json:"inputParameters"`
// Application specific, user-defined data. Implementers
// may use this field to store arbitrary data for a session.
// Implementers are responsible for passing this data to the
// command Output, and are free to modify it however they
// want (or clear it entirely).
Metadata string `json:"metadata"`
}
Input contains the command input data as received from Diatheke.
type Output ¶ added in v1.1.0
type Output struct {
// The ID of the command that was executed
CommandID string `json:"id"`
// Parameters that Diatheke expects to be returned (possibly
// empty).
Parameters Params `json:"outParameters,omitempty"`
// Application specific, user-defined data to associate
// with the session that executed this command.
Metadata string `json:"metadata,omitempty"`
// An error message to indicate to Diatheke that something
// went wrong during command execution. Most implementers
// won't need to set this field directly as it set by the
// server when an error is returned from the handler.
Error string `json:"error,omitempty"`
}
Output contains the command data to send back to Diatheke.
type Params ¶
Params is an alias for a map[string]string that includes some convenience functions for converting to other types. To create a new Params object, use the go standard make function (e.g., `make(Params)`). Note that the convenience functions are not safe to use concurrently (just as it is not safe to access a regular map in Go concurrently).
func (Params) AsBool ¶
AsBool returns the parameter value for the given key as a bool. Returns an error if the key was not found or there was a problem during conversion.
func (Params) AsFloat32 ¶
AsFloat32 returns the parameter value for the given key as a float32. Returns an error if the key was not found or there was problem during conversion.
func (Params) AsFloat64 ¶
AsFloat64 returns the parameter value for the given key as a float64. Returns an error if the key was not found or there was a problem during conversion.
func (Params) AsInt ¶
AsInt returns the parameter value for the given key as an int. Returns an error if the key was not found or there was a problem during conversion.
func (Params) AsString ¶
AsString returns the parameter value for the given key as a string. Returns an error if the key was not found. Note that the underlying map may be used directly to get the parameter and check it's existence without the error (e.g., `val, ok := p[key]`).
func (Params) SetBool ¶
SetBool converts the given bool to a string and stores it in the parameter map.
func (Params) SetFloat32 ¶
SetFloat32 converts the given float32 to a string and stores it in the parameter map. This uses the 'g' formatting style for the conversion, with a precision of 4. For different formatting, it is recommended to use strconv.FormatFloat().
func (Params) SetFloat64 ¶
SetFloat64 converts the given float64 to a string and stores it in the parameter map. This uses the 'g' formatting style for the conversion, with a precision of 4. For different formatting, it is recommended to use strconv.FormatFloat().
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server represents an http server that handles Diatheke commands. With this server, all commands go to the same URL, so the Diatheke model should be set accordingly. Once received, commands are sent to Handlers added with the SetHandler function.
func (*Server) Run ¶
Run starts the http server and listens at the given address (e.g., ":8072", "localhost:1515", "127.0.0.1:3535") until either an error occurs or the interrupt signal is received.
func (*Server) ServeHTTP ¶
func (svr *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)
ServeHTTP implements the http.Handler interface. It decodes the command, forwards the data to the correct command Handler, then encodes the result to send back to Diatheke.
func (*Server) SetCommand ¶ added in v1.1.0
SetCommand registers the provided Handler to be called for the specified command ID.
If there are multiple potential handlers for a command registered (using SetCommand, SetModel, or SetModelCommand) the server will attempt to use the most specific handler available, with precedence shown below:
- Model+Command ID handler (most specific)
- Command ID handler
- Model ID handler (least specific)
func (*Server) SetModel ¶ added in v1.1.0
SetModel registers the provided Handler to be called for the specified model ID.
If there are multiple potential handlers for a command registered (using SetCommand, SetModel, or SetModelCommand) the server will attempt to use the most specific handler available, with precedence shown below:
- Model+Command ID handler (most specific)
- Command ID handler
- Model ID handler (least specific)
func (*Server) SetModelCommand ¶ added in v1.1.0
SetModelCommand registers the provided Handler to be called for the given model and command ID combination.
If there are multiple potential handlers for a command registered (using SetCommand, SetModel, or SetModelCommand) the server will attempt to use the most specific handler available, with precedence shown below:
- Model+Command ID handler (most specific)
- Command ID handler
- Model ID handler (least specific)
Source Files