ghoko

README

GHoKo

GHoKo is a web application that listens to web-hooks, scripted by Lua and written in Golang. Web-hooks usually are used for CI, Automated testing or something else.

For example, GHoKo has been used in many browser based game projects for CI and system operations.

Dependency

• mikespook/golib
• aarzilli/golua
• stevedonovan/luar
• liblua5.1-0-dev for Ubuntu

Installing

All useful scripts were put at the directory shell.

Befor building, the proper lua librarie must be installed. E.g. Ubuntu 14.04, it is liblua5.1-0-dev.

Then:

go get github.com/mikespook/ghoko/ghoko

The ghoko library implement http.Handler and can be embeded into other projects.

go get github.com/mikespook/ghoko

Have a fun!

Usage

Service

Executing following command:

$ ${fullpath}/ghoko -h

Some help information:

Usage of ./ghoko:
	-addr=":8080": Address of http service
	-defualt="gitlab": Default code hosting site
	-log="": log to write (empty for STDOUT)
	-log-level="all": log level ('error', 'warning', 'message', 'debug', 
		'all' and 'none' are combined with '|')
	-pid="": PID file
	-root="/": Root path of URL
	-script="./": Path of lua files
	-secret="": Secret token
	-tls-cert="": TLS cert file
	-tls-key="": TLS key file

The pattern of hook URL is

${schema}://${addr}/${root}/${hook}?_secret=${secret}&${params}

$schema could be HTTP or HTTPS either. When both two tls-* flags were specified correctly, The HTTPS will be used.

You can set root path of URL through root flag.

Eg. script was set to /ghoko. And if root is /hook/v1, the request http://127.0.0.1:3080/hook/v1/foo/bar will evaluate /ghoko/foo/bar.lua. If root was set to /hook and requesting the same URL, /ghoko/v1/foo/bar.lua will be evaluated.

$params can be used for passing custom values into script through URL. HTTP method, POST is also accepted. If Content-Type in the request header contains json, it means passing enconded JSON data through POST-Body. Otherwise, it is a common post with form data.

All of them will combine into a global variable ghoko.Params, it can be used in Lua scripts.

Usually, GHoKo evaluates lua scripts asynchronous. Ghoko-Sync is a magic header for requesting ghoko in synchronized way. When it is equal ture(string), two functions ghoko.WriteBody and ghoko.WriteHeader can be used for response data and HTTP status to HTTP clients.

Another magic header is GHoKo-Id. It tells ghoko do not generate ID but using client specified one.

Scripting

GHoKo use Lua as the scripting language. GHoKo will pass the Request into Lua script as a user data.

You can use user data in the Lua script.

Following variables and functions can be called in Lua:

• ghoko.Id - Every request has a global unique Id
• ghoko.Params - Params passed by URL\POST-BODY(JSON format)
• ghoko.Call(id, name, params) - Call lua script and pass params to it
• ghoko.Debug(msg)/ghoko.Debugf(format, msg) - Output debug infomations
• ghoko.Message(msg)/ghoko.Messagef(format, msg) - Output message infomations
• ghoko.Warning(msg)/ghoko.Warningf(format, msg) - Output warning infomations
• ghoko.Error(err)/ghoko.Errorf(format, msg) - Output error infomations
• ghoko.Write(msg) - Write something to HTTP clients (sync only)
• ghoko.WriteHeader(status) - Assign HTTP status (sync only)
• ghoko.Get(url) - GET a remote url, _secret will be passed
• ghoko.PostJSON(url, params) - POST to a remote url with JSON encoded params
• ghoko.Post(url, params) - POST to a remote url with a form

Web Hook

To set GitLab's web hook: Your repo --> settrings --> Web Hooks.

To set GitHub's web hook is a little more complicated. Following: Your repo --> Settings --> Service Hooks --> WebHook URLs.

Here is an example for gitlab (gitlab.lua):

http://192.168.1.100/gitlab?_secret=phrase

or for github (github.lua):

http://192.168.1.100/github?_secret=phrase

We have writen demo scripts for you. The scripts will print the repo and commits's informations.

Authors

• Xing Xing mikespook@gmail.com Blog @Twitter

Open Source

See LICENSE for more information.

Documentation

Index

• Variables
• func CallbackUrl(tlsCert, tlsKey, addr, root string) string
• func NewLuaIpt() iptpool.ScriptIpt
• type Handler
  • func New(scriptPath, secret, rootUrl string) (h *Handler)
  • func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type HttpError
  • func (err *HttpError) Error() string
• type LuaIpt
  • func (luaipt *LuaIpt) Bind(name string, item interface{}) error
  • func (luaipt *LuaIpt) Exec(name string, params interface{}) error
  • func (luaipt *LuaIpt) Final() error
  • func (luaipt *LuaIpt) Init(path string) error
• type Params
  • func (p Params) AddJSON(data []byte) (err error)
  • func (p Params) AddValues(values url.Values)
  • func (p Params) Values() url.Values

Variables

var (
	ErrSyncNeeded = &HttpError{http.StatusBadRequest, "`Ghoko-sync` header needed"}
	ErrForbidden  = &HttpError{http.StatusForbidden, "Incorrect `_secret` parameter"}
	ErrNotFound   = &HttpError{http.StatusNotFound, "Request path was not found"}
)

Functions

func CallbackUrl

func CallbackUrl(tlsCert, tlsKey, addr, root string) string

func NewLuaIpt

func NewLuaIpt() iptpool.ScriptIpt

Types

type Handler

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

func New

func New(scriptPath, secret, rootUrl string) (h *Handler)

func (*Handler) ServeHTTP

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

type HttpError

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

func (*HttpError) Error

func (err *HttpError) Error() string

type LuaIpt

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

func (*LuaIpt) Bind

func (luaipt *LuaIpt) Bind(name string, item interface{}) error

func (*LuaIpt) Exec

func (luaipt *LuaIpt) Exec(name string, params interface{}) error

func (*LuaIpt) Final

func (luaipt *LuaIpt) Final() error

func (*LuaIpt) Init

func (luaipt *LuaIpt) Init(path string) error

type Params

type Params luar.Map

func (Params) AddJSON

func (p Params) AddJSON(data []byte) (err error)

func (Params) AddValues

func (p Params) AddValues(values url.Values)

func (Params) Values

func (p Params) Values() url.Values