From an idea by tasn.

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

i got tired of rereading the source code every time i wanted to use irk, isn't that silly?

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

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

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

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

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

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

Respect the 'socket' argument passed in by the caller.  Fixes a typo
introducted in a82724f9 (irkerd: Initial SSL/TLS implementation,
2014-03-06).

This fixes some problems with -i/--immediate parsing in ccd311c5
(irkerd: Transition from getopt to argparse, 2014-03-06).

> +    parser.add_argument(
> +        '-i', '--immediate', action='store_const', const=True,
> +        help='disconnect after sending each message')

This does not match the old syntax where -i took two arguments (an IRC
URL and a message).

> -    if immediate:
> +    if args.immediate:
>          irker.irc.add_event_handler("quit", lambda _c, _e: sys.exit(0))
>          irker.handle('{"to":"%s","privmsg":"%s"}' % (immediate, arguments[0]), quit_after=True)
>          irker.irc.spin()

immediate should be args.immediate, and arguments[0] needs to be added
as a new (optional) positional argument.

This patch fixes both issues.

And use them (when present) as the USER username [1] and server PASS
[2] respectively.  The previous implementation gave no way to set
PASS, which will vary on a per-target-server level.  There's unlikely
to be much need to set per-server usernames, except collision
avoidance (e.g. network X already has an 'irker' user).

I changed the existing IRCServerConnection.connect argument from
'ircname' to 'realname' to match the USER specs and our
IRCServerConnection.user implementation.  The 'realname' and
'username' arguments are currently unset, but you could add command
line options to set irker-wide defaults, and use the kwargs chain to
pass them down to the connect method.  The fallback logic is:

* Prefer the setting listed in the URL (although you'd need to add a
  parser to extract 'realname').  If that's empty or missing, fall
  back to
* The irker-wide default passed down the kwargs chain.  If that's
  empty or missing, fall back to
* Local defaults ('irker' and 'irker relaying client').

I also tweaked the servername and port extraction in
Target.__init__(), because they are already parsed out of the netloc
(along with the username and password) by urlparse().

[1]: https://tools.ietf.org/html/rfc2812#section-3.1.3
[2]: https://tools.ietf.org/html/rfc2812#section-3.1.1

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.