This is pretty basic, just using as much of Python's ssl module as the
host Python implementation supports.  I also added error-level logging
of IRCServerConnectionError instances, to get helpful messages like:

  Invalid SSL/TLS certificate:
  hostname 'localhost' doesn't match 'irc.example.net'

and:

  Couldn't connect to socket: _ssl.c:334: No root certificates
  specified for verification of other-side certificates.

Important milestones in the standard library's ssl module:

* Python 2.5 [1,2]: No ssl module at all
* Python 2.6 [1,2]: ssl module added
* Python 3.2 [3,4]: ssl.SSLContext class added, with
  SSLContext.set_default_verify_paths [4].  ssl.match_hostname is also
  added [5], which can be used with the existing getpeercert [6] to
  ensure the server certificate belongs to the target host.

So for full verification, we need Python 3.2.  We can scrape by with
2.6 and later, by manually supplying a ca_certs path and ignoring
hostname mismatches.  That's more succeptible to man-in-the-middle
attacks, but still better than sending server, nick, and channel
passwords in plaintext.

[1]: http://docs.python.org/2/library/ssl.html
[2]: http://docs.python.org/2/whatsnew/2.6.html#improved-ssl-support
[3]: http://docs.python.org/3/whatsnew/3.2.html#ssl
[4]: http://docs.python.org/3/library/ssl.html#ssl.SSLContext.set_default_verify_paths
[5]: http://docs.python.org/3/library/ssl.html#ssl.match_hostname
[6]: http://docs.python.org/2/library/ssl.html#ssl.SSLSocket.getpeercert

The former was giving me:

  Traceback (most recent call last):
    File "/usr/lib64/python3.3/threading.py", line 901, in _bootstrap_inner
      self.run()
    File "/usr/lib64/python3.3/threading.py", line 858, in run
      self._target(*self._args, **self._kwargs)
    File "./irkerd", line 637, in dequeue
      LOG.debug(e.format_exc())
  AttributeError: 'TypeError' object has no attribute 'format_exc'

In Python 3.3.4.

This implements the necessary changes to work around the (str,
unicode) -> (bytes, str) transition.  We decode the bytes as soon as
possible after receiving them in the Irker*Handler classes.  For
IRC-side connections, we still encode outgoing data right before
sending it in IRCServerConnection.ship.

We decode incoming IRC-side bytes in IRCServerConnection.consume,
after storing them as bytes in the LineBufferedStream
IRCServerConnection.buffer.  That ensures that we don't try and decode
partial code points which are split across two socket messages.

That's what 'self' is for ;).  Also prefix 'crlf_re' with an
underscore to mark it as private data, and not part of
LineBufferedStream's API.

Prefer the Python 3 names to the Python 2 names for forward
compatibility.

Now that we've dropped support for Python 2.5, we don't need this
workaround anymore.

Since we no longer officially support Python 2.5, there's no *need* to
use a fallback JSON library.  Removing it makes our dependencies
cleaner, and JSON-parsing speed is not likely to be a large fraction
of irkerd cycles anyway.

Support for this was added in Python 2.6 and 3.0.  We can't have
Python 3 compatibility without removing the old "except x, y" syntax,
and I think 3.x support is more imporant than 2.5 support.  In any
case, the existing irkerd has been using the new syntax since 3cc87513
(Truncate messages that are longer than 512 bytes and catch any
exceptions irclib throws about rejected messages, 2013-01-21), so this
commit is not a *new* break with 2.5 support.

Thie makes logging more consistent with other errors (e.g. you can
adjust the logging Handler and get all the errors sent to syslog or a
file).  I also removed the 'irkerd: ' prefix; if we want that, I think
we should add it to all logged messages by using a custom string in
the logging Formatter.

Print statements are gone in Python 3, so this removes a barrier to
Python 3 support.  It also makes the logging more consistent with
other errors (e.g. the StreamHandler will print it to stdout, while
the print statement was sending it to stderr).

This gives us long options and removes the need to code our own usage
string and choice-base argument processing.  I also removed the blurb
about options from the module docstring, to avoid duplicating
information.

Using the new kwargs handling to pass the data through Irker() down to
Connection().  Note that this is the nickserv password, not the
server-wide login password used by Connection.connect().

Using the new kwargs handling to pass the data through Irker() down to
Connection().  I think 'nick_template' more clearly reflects
the contents of this variable.

Using the new kwargs handling to pass the data through Irker() down to
Connection().

This makes it easy to pass data down the stack:

  Irker() (stored in Irker.kwargs)
  `-- Irker.handle() -> Dispatcher() (stored in Dispatcher.kwargs)
      `-- Dispatcher.dispatch() -> Connection() (stored in Connection.kwargs)
          `-- Connection.dequeue() -> IRCServerConnection.connect()

You can easily add data at every point in the stack (e.g. we add
'target' in Irker.handle()) and pull it back out when that's
appropriate (e.g. we tap 'target' back out in Connection()).  With
this setup we can reduce the number of global variables currently in
use, because it will be easy to pass data like passwords,
nickame-fallback-ness, etc. down to the appropriate level, without the
intermediate levels needing any changes.

Prefer the servername, falling back to the URL, falling back to
Target.__repr__().

Instead of using the local IRCClient.debug() method, use the more
flexible standard library logger.  This makes it easy to log to
syslog, rotating files, etc, using the usual logging Handlers.  The
mapping from the old implementation to the new implementation is:

  IRCClient.debug(1, message)  -> LOG.info(message)
  IRCClient.debug(2, message)  -> LOG.debug(message)
  IRCClient.debug(50, message) -> LOG.debug(message)
  Irker.logerr(errmsg)         -> LOG.error(message)

with the exception of the failed-message error, which is logged as
LOG.warning().  I didn't try and recategorize the other message log
levels, although I think a number of info-level log messages should
really be debug-level log messages.

To set the log level, the -d option now takes string arguments
(e.g. 'info', 'debug') instead of numeric arguments (e.g. '1', '2').
This breaks backward compatibility, but I think it makes the argument
more user-friendly.  If you try and set an invalid level, there's a
helpful error message to guide you in the right direction.

I also use format_exc() in Connection.dequeue (following the existing
example deeper in the Connection.dequeue nest).  The log level should
decide whether the traceback is printed or not, not whether the
exception should be raised or ignored.

Following PEP 8 [1]:

  Imports should usually be on separate lines, e.g.:

    Yes: import os
         import sys

    No:  import sys, os

This also makes it easier to read diffs that add and remove imports,
since you won't need a word-diff to see exactly what changed.

[1]: http://legacy.python.org/dev/peps/pep-0008/#imports

Conflicts:
	irkerd

There is a lot of error checking here, which is good, but it distracts
from the core logic of Irker.handle.  By pulling the parsing out into
a private helper function, we isolate the code focused on parsing and
error checking from the code focused on dispatching and connection
management, making both easier to read.

I've also changed the Target-validation logic.  The old Target.valid
returned True if the Target URL was valid, and False otherwise.  The
new Target.validate returns None, and raises an InvalidRequest
exception with an error message describing exactly why the URL is
invalid.  We print these messages when dropping server URLs in
Irker._parse_request, while the old Irker.handle code silently dropped
invalid targets.  We also continue processing other server URLs after
an invalid Target, while the old Irker.handle code bailed out after
the first invalid Target.  Besides making the invalid URLs more
obvious in the logs and increasing resiliency to invalid URLs, these
changes allow us to pull the URL-to-Target conversion out of
Irker.handle entirely, so it can focus more strongly on dispatch and
connection management.

The old implementation had several instances of logic like this:

  if exception_condition:
      self.logerr("invalid request")
  else:
      # continue_processing

This increases nesting after each round of exception checking, and
makes the logic of the whole function harder to follow.  This commit
replaces that logic with:

  try:
      if exception_condition:
          raise InvalidRequest("invalid request")
      # continue peocessing
  except InvalidRequest, e:
      self.logerr(str(e))

Because the guts of the handle() function are already inside a
try/except block, we can add our except clause to the existing block,
and now exception checks don't increase nesting at all.

The exception to this global try/except block is the 'URL has
unexpected type' error, where we do want a local try/except block
inside the channel loop.  That way we get both errors about invalid
URLs and continue to attempt valid URLs.  This matches the existing
logic for this check, but conflicts with the current target.valid
check (which doesn't log an error and does stop processing of further
channels).

We will never need the connection-time port, server_address, username,
ircname, or password again, so don't store them.  We *do* need server
and real_server_name for Event handling, so keep them around.

Otherwise, it would crash if any unicode string was already
present.

Signed-off-by: Eric S. Raymond <esr@thyrsus.com>

this fixes the following backtrace:

Exception happened during processing of request from ('127.0.0.1', 41192)
Traceback (most recent call last):
  File /usr/lib/python2.7/SocketServer.py, line 295, in _handle_request_noblock
    self.process_request(request, client_address)
  File /usr/lib/python2.7/SocketServer.py, line 321, in process_request
    self.finish_request(request, client_address)
  File /usr/lib/python2.7/SocketServer.py, line 334, in finish_request
    self.RequestHandlerClass(request, client_address, self)
  File /usr/lib/python2.7/SocketServer.py, line 649, in __init__
    self.handle()
  File ./irkerd, line 820, in handle
    irker.handle(line.strip())
  File ./irkerd, line 786, in handle
    self.servers[target.server()].dispatch(target.channel, message, target.key, quit_after=quit_after)
  File ./irkerd, line 641, in dispatch
    eligibles[0].enqueue(channel, message, key)
TypeError: enqueue() takes exactly 5 arguments (4 given)

when running: ./irk irker-test test

the previous suggestion seemed to be about the update hook, but it's
usually bad practice to setup notification hooks there, because if
they fail, the push fails.

parsing the git documentation to find exactly the incantation is not
exactly trivial either...