Initial docs

acceptor/tcp_acceptor.go

@@ -122,5 +122,4 @@ func (a *TCPAcceptor) serve() {
 		}
 		a.connChan <- conn
 	}
-
 }

app.go

@@ -149,7 +149,7 @@ func Configure(
 			logger.Log.Errorf("failed to start statds metrics reporter, skipping %v", err)
 		} else {
 			logger.Log.Info("successfully configured statsd metrics reporter")
-			app.metricsReporters = append(app.metricsReporters, metricsReporter)
+			AddMetricsReporter(metricsReporter)
 		}
 	}
 }

docs/API.md

@@ -0,0 +1,98 @@
+Pitaya API
+==========
+
+## Handlers
+
+Handlers are one of the core features of Pitaya, they are the entities responsible for receiving the requests from the clients and handling them, returning the response if the method is a request handler, or nothing, if the method is a push handler.
+
+### Signature
+
+Handlers must be public methods of the struct and have a signature following:
+
+Arguments
+* `context.Context`: the context of the request, which contains the client's session.
+* `pointer or []byte`: the payload of the request (_optional_).
+
+Push handlers return nothing, while request handlers must return:
+* `pointer or []byte`: the response payload
+* `error`: an error variable
+
+
+### Registering handlers
+
+Handlers must be explicitly registered by the application by calling `pitaya.Register` with a instance of the handler component. The handler's name can be defined by calling `pitaya/component`.WithName(`"handlerName"`) and the methods can be renamed by using `pitaya/component`.WithNameFunc(`func(string) string`).
+
+The clients can call the handler by calling `serverType.handlerName.methodName`.
+
+
+### Routing messages
+
+Messages are forwarded by pitaya to the appropriate server type, and custom routers can be added to the application by calling `pitaya.AddRoute`, it expects two arguments:
+
+* `serverType`: the server type of the target requests to be routed
+* `routingFunction`: the routing function with the signature `func(*session.Session, *route.Route, []byte, map[string]*cluster.Server) (*cluster.Server, error)`, it receives the user's session, the route being requested, the message and the map of valid servers of the given type, the key being the servers' ids
+
+The server will then use the routing function when routing requests to the given server type.
+
+
+### Lifecycle Methods
+
+Handlers can optionally implement the following lifecycle methods:
+
+* `Init()` - Called by Pitaya when initializing the application
+* `AfterInit()` - Called by Pitaya after initializing the application
+* `BeforeShutdown()` - Called by Pitaya when shutting down components, but before calling shutdown
+* `Shutdown()` - Called by Pitaya after the start of shutdown
+
+
+### Handler example
+
+Below is a very barebones example of a handler definition, for a complete working example, check the [cluster demo](https://github.com/topfreegames/pitaya/tree/master/examples/demo/cluster).
+
+```go
+import (
+  "github.com/topfreegames/pitaya"
+  "github.com/topfreegames/pitaya/component"
+)
+
+type Handler struct {
+  component.Base
+}
+
+type UserRequestMessage struct {
+  Name    string `json:"name"`
+  Content string `json:"content"`
+}
+
+type UserResponseMessage {
+}
+
+type UserPushMessage{
+  Command string `json:"cmd"`
+}
+
+// Init runs on service initialization (not required to be defined)
+func (h *Handler) Init() {}
+
+// AfterInit runs after initialization (not required to be defined)
+func (h *Handler) AfterInit() {}
+
+// TestRequest can be called by the client by calling <servertype>.testhandler.testrequest
+func (h *Handler) TestRequest(ctx context.Context, msg *UserRequestMessage) (*UserResponseMessage, error) {
+  return &UserResponseMessage{}, nil
+}
+
+func (h *Handler) TestPush(ctx context.Context, msg *UserPushMessage) {
+}
+
+func main() {
+  pitaya.Register(
+    &Handler{}, // struct to register as handler
+    component.WithName("testhandler"), // name of the handler, used by the clients
+    component.WithNameFunc(strings.ToLower), // naming conversion scheme to be used by the clients
+  )
+
+  ...
+}
+
+```

docs/Makefile

@@ -0,0 +1,21 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SPHINXPROJ    = Pitaya
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+

docs/conf.py

@@ -0,0 +1,160 @@
+# -*- coding: utf-8 -*-
+#
+# Configuration file for the Sphinx documentation builder.
+#
+# This file does only contain a selection of the most common options. For a
+# full list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+from recommonmark.parser import CommonMarkParser
+
+source_parsers = {
+    '.md': CommonMarkParser,
+}
+
+# -- Project information -----------------------------------------------------
+
+project = u'Pitaya'
+copyright = u'2018, TFGCo'
+author = u'TFGCo'
+
+# The short X.Y version
+version = u''
+# The full version, including alpha/beta/rc tags
+release = u''
+
+
+# -- General configuration ---------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+source_suffix = ['.rst', '.md']
+# source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path .
+exclude_patterns = [u'_build', 'Thumbs.db', '.DS_Store']
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+# html_theme_options = {}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# Custom sidebar templates, must be a dictionary that maps document names
+# to template names.
+#
+# The default sidebars (for documents that don't match any pattern) are
+# defined by theme itself.  Builtin themes are using these templates by
+# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
+# 'searchbox.html']``.
+#
+# html_sidebars = {}
+
+
+# -- Options for HTMLHelp output ---------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'Pitayadoc'
+
+
+# -- Options for LaTeX output ------------------------------------------------
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    #
+    # 'papersize': 'letterpaper',
+
+    # The font size ('10pt', '11pt' or '12pt').
+    #
+    # 'pointsize': '10pt',
+
+    # Additional stuff for the LaTeX preamble.
+    #
+    # 'preamble': '',
+
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, 'Pitaya.tex', u'Pitaya Documentation',
+     u'TFGCo', 'manual'),
+]
+
+
+# -- Options for manual page output ------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'pitaya', u'Pitaya Documentation',
+     [author], 1)
+]
+
+
+# -- Options for Texinfo output ----------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (master_doc, 'Pitaya', u'Pitaya Documentation',
+     author, 'Pitaya', 'One line description of project.',
+     'Miscellaneous'),
+]