start of more docs wrt configuration

conf/perlbal.conf

@@ -1,16 +1,15 @@
-# comments work
-
 SERVER max_connections = 10000
-# + 4 (stdin,out,err,epoll)
+
+SERVER aio_mode = ioaio    # use IO::AIO
+#SERVER aio_mode = linux   # use Linux::AIO
+#SERVER aio_mode = none    # don't use non-blocking disk I/O (okay for proxies, BAD for webservers)
 
 # load some plugins
 #LOAD stats
 #LOAD queues
 #LOAD palimg
 
 #SET buffer_size = 250k
-#SET min_rate = 2k
-#SET min_rate_check = 10s
 #SET user = nobody.nogroup
 
 # globally, no more than 20 connections to each reproxy host
@@ -142,26 +141,27 @@ SET web.persist_client = 1
 ENABLE web
 
 CREATE SERVICE mgmt
-SET mgmt.role = management
-SET mgmt.listen = 0.0.0.0:8065
+  SET mgmt.role = management
+  SET mgmt.listen = 0.0.0.0:8065
 ENABLE mgmt
 
 # create a palimg service that will handle pallette altering GIFs and PNGs
 #CREATE SERVICE web_palimg
-#SET web_palimg.plugins = stats, palimg
-#SET web_palimg.listen = 0.0.0.0:8083
-#SET web_palimg.docroot = /usr/share/
-# It will search in /usr/share/palimg/ for images.
+#  SET web_palimg.plugins = stats, palimg
+#  SET web_palimg.listen = 0.0.0.0:8083
+#  SET web_palimg.docroot = /usr/share/
+#   # It will search in /usr/share/palimg/ for images.
 #ENABLE web_palimg
 
 # and now create an upload service that lets people PUT files to it
 #CREATE SERVICE upload
-#SET upload.role = web_server
-#SET upload.enable_put = yes
-#SET upload.max_upload_size = 150000
+#  SET upload.role = web_server
+#  SET upload.enable_put = yes
+#  SET upload.max_upload_size = 150000
 # Maximum file size of 150,000 bytes.  Set to 0 for no limit.
-#SET upload.listen = 0.0.0.0:8084
-#SET upload.docroot = /usr/share/upload/
+#
+#  SET upload.listen = 0.0.0.0:8084
+#  SET upload.docroot = /usr/share/upload/
 # All files will be put into /usr/share/upload/ as a base.
 #ENABLE upload
 

conf/webserver.conf

@@ -0,0 +1,15 @@
+#
+# This is an example webserver configuration.
+#
+# See doc/ConfigGuide.txt for descriptions of each command (line)
+# and configuration syntax.
+#
+
+CREATE SERVICE docs
+  SET docs.listen = 0.0.0.0:80
+  SET docs.role = web_server
+  SET docs.docroot = /usr/share/doc/
+  SET docs.dirindexing = 1
+  SET docs.persist_client = on
+  SET docs.persist_client = on
+ENABLE docs

doc/Classes.txt

@@ -22,7 +22,10 @@ conforms to HTTP specifications.
 ClientHTTPBase -- descends from Perlbal::Socket
   Provides base functionality to ClientHTTP and ClientProxy.  Notably, the
 ability to efficiently send files to the remote user.  Also handles most of
-the state logic for statistics and such.
+the state logic for statistics and such. Is also used for services of type
+"selector".  The ClientHTTPBase then reads in the request headers, and asks
+the service to re-bless the client instance to a more specific type, for
+either a ClientProxy or ClientHTTP (depending on selector's mapping).
 
 ClientHTTP -- descends from Perlbal::ClientHTTPBase
   Very simple and lightweight class.  Handles sending files to the user

doc/ConfigGuide.txt

@@ -0,0 +1,36 @@
+All Perlbal configuration commands:
+===================================
+
+Admin commands:
+- - - - - - - -
+shutdown                   -- shuts down the server, killing all active connections
+shutdown graceful          -- closes listening sockets and stays alive until clients bleed off
+xs                         -- show status of XS modules loaded
+xs enable <module>         -- turn on an already-loaded XS module
+xs disable <module>        -- turn off an already-loaded XS module
+
+
+
+
+Diagnostic commands:
+- - - - - - - - - -
+obj                        -- shows objects counts in scope
+fd                         -- show file descriptors in use
+proc                       -- show CPU usage, current time, pid, and total requests processed
+nodes                      -- show BackendHTTP statistics for all backend nodes
+node <ip[:port]>           -- show BackendHTTP statistics for specified node
+prof on                    -- enable profiling
+prof off                   -- disable profiling
+prof data                  -- dump profile data
+uptime                     -- show time server was started, and current uptime
+track                      -- dump out objects tracked, sorted by age
+
+backends
+noverify
+pending
+states
+
+
+
+
+

doc/Hooks.txt

@@ -1,3 +1,6 @@
+TO_DOCUMENT:
+  -- hooking management commands
+
 Perlbal Hooks --
 
                             -- INTRODUCTION --

doc/README.txt

@@ -1,7 +1,7 @@
-Perlbal is not yet documented.
+Perlbal is probably not documented enough.
 
-See the website, conf/ directory for examples, and post questions on
-the mailing list for now.
+See the website, doc/ directory, and conf/ directory for examples, and
+post questions on the mailing list for now.
 
 Website:
 http://www.danga.com/perlbal/

doc/todo.txt

@@ -10,20 +10,29 @@
 * Investigate when BackendHTTP fails on a call to get_res_headers?
 
 * Fix shutdown graceful to close off persistent clients and bored backends (reproxy too?)
+  (This is done already?)
 
 * Document the 'reproxy bored' queue [old...new] self cleaning on the old side, but
   uses the new side when it needs a connection
 
-* Investigate why Perlbal is slow to accept connections
-
 * Lots of work can be done to reduce system calls:
   - coalesce epoll_ctl calls
   - make socket by hand without IO::Socket::INET
-  - edge-triggered epoll in Danga::Socket
   - don't cork twice on reproxy & send
 
 * Support dictionary (scratch hash) per service
   - can configure keys to send to backends
   - backends can set keys in dictionary (so they propogate to other backends, etc)
 
 * Allow configurable response code that means "backend dead; replay request"
+
+* Plugins to say what HTTP requests are known idempotent and re-playable in case
+  of errors.  Also option to say that all GETs or urls matching certain rules
+  are idempotent
+
+* rule service selector
+
+* way for management commands to hold state (absorbing all future commands)
+  .. for defining rules, etc
+
+* let rules map to pools (selectors), or set things like idempotent