From 1a6160ebeecffc57b5066ebf343188edf6a63eaa Mon Sep 17 00:00:00 2001
From: "Chris St. Pierre" <chris.a.st.pierre@gmail.com>
Date: Fri, 12 Oct 2012 11:37:14 -0400
Subject: wrote sphinx docs for base server Core

---
 doc/development/core.txt | 62 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 62 insertions(+)
 create mode 100644 doc/development/core.txt

(limited to 'doc/development/core.txt')

diff --git a/doc/development/core.txt b/doc/development/core.txt
new file mode 100644
index 000000000..145be3338
--- /dev/null
+++ b/doc/development/core.txt
@@ -0,0 +1,62 @@
+.. -*- mode: rst -*-
+
+.. _development-core:
+
+=========================
+ Server Core Development
+=========================
+
+.. versionadded:: 1.3.0
+
+Bcfg2 1.3 added a pluggable server core system so that the server core
+itself can be easily swapped out to use different technologies.  It
+currently ships with two backends: a builtin core written from scratch
+using the various server tools in the Python standard library; and an
+experimental `CherryPy <http://www.cherrypy.org/>`_ based core.  This
+page documents the server core interface so that other cores can be
+written to take advantage of other technologies, e.g., `Tornado
+<http://www.tornadoweb.org/>`_ or `Twisted
+<http://twistedmatrix.com/trac/>`_.
+
+A core implementation needs to:
+
+* Override :func:`Bcfg2.Server.Core.Core._daemonize` to handle
+  daemonization, writing the PID file, and dropping privileges.
+* Override :func:`Bcfg2.Server.Core.Core._run` to handle server
+  startup.
+* Override :func:`Bcfg2.Server.Core.Core._block` to run the blocking
+  server loop.
+* Call :func:`Bcfg2.Server.Core.Core.shutdown` on orderly shutdown.
+
+Nearly all XML-RPC handling is delegated entirely to the core
+implementation.  It needs to:
+
+* Call :func:`Bcfg2.Server.Core.Core.authenticate` to authenticate
+  clients.
+* Handle :exc:`xmlrpclib.Fault` exceptions raised by the exposed
+  XML-RPC methods as appropriate.
+* Dispatch XML-RPC method invocations to the appropriate method,
+  including Plugin RMI.
+
+Additionally, running and configuring the server is delegated to the
+core.  It needs to honor the configuration options that influence how
+and where the server runs, including the server location (host and
+port), listening interfaces, and SSL certificate and key.
+
+Base Core
+=========
+
+.. automodule:: Bcfg2.Server.Core
+
+Core Implementations
+====================
+
+Builtin Core
+------------
+
+.. automodule:: Bcfg2.Server.BuiltinCore
+
+CherryPy Core
+-------------
+
+.. automodule:: Bcfg2.Server.CherryPyCore
-- 
cgit v1.2.3-1-g7c22