update comments

[erebus.git] / modlib.py

# Erebus IRC bot - Author: John Runyon
# vim: fileencoding=utf-8
# module helper functions, see modules/modtest.py for usage
# This file is released into the public domain; see http://unlicense.org/

import sys
import socket
from functools import wraps

if sys.version_info.major < 3:
	stringbase = basestring
else:
	stringbase = str

"""Used to return an error to the bot core."""
class error(object):
	def __init__(self, desc):
		self.errormsg = desc
	def __nonzero__(self):
		return False #object will test to False
	__bool__ = __nonzero__ #py3 compat
	def __repr__(self):
		return '<modlib.error %r>' % self.errormsg
	def __str__(self):
		return str(self.errormsg)

class modlib(object):
	# default (global) access levels
	OWNER   = 100
	MANAGER =  99
	ADMIN   =  75
	STAFF   =  50
	KNOWN   =   1
	AUTHED  =   0 # Users which have are known to be authed
	ANYONE  =  -1 # non-authed users have glevel set to -1
	IGNORED =  -2 # If the user is IGNORED, no hooks or chanhooks will fire for their messages. numhooks can still be fired.
	glevs   = {
		'OWNER': OWNER,
		'MANAGER': MANAGER,
		'ADMIN': ADMIN,
		'STAFF': STAFF,
		'KNOWN': KNOWN,
		'AUTHED': AUTHED,
		'ANYONE': ANYONE,
		'IGNORED': IGNORED,
	}

	# (channel) access levels
	COWNER  =   5
	MASTER  =   4
	OP      =   3
	VOICE   =   2
	FRIEND  =   1
	PUBLIC  =   0 # Anyone (use glevel to control whether auth is needed)
	BANNED  =  -1 # The default reqclevel is PUBLIC, so any commands which needchan will be ignored from BANNED users unless the command reqclevel=-1
	#         [   0         1        2     3         4        5    -1]
	clevs   = [None, 'Friend', 'Voice', 'Op', 'Master', 'Owner', 'Banned']

	# messages
	WRONGARGS = "Wrong number of arguments."

	def __init__(self, name):
		self.hooks = {} # {command:handler}
		self.chanhooks = {} # {channel:handler}
		self.exceptionhooks = [] # [(exception,handler)]
		self.numhooks = {} # {numeric:handler}
		self.sockhooks = [] # [(af,ty,address,handler_class)]
		self.sockets = [] # [(sock,obj)]
		self.helps = []
		self.parent = None

		self.name = (name.split("."))[-1]

	def modstart(self, parent):
		#modstart can return a few things...
		# None: unspecified success
		# False: unspecified error
		# modlib.error (or anything else False-y): specified error
		# True: unspecified success
		# non-empty string (or anything else True-y): specified success
		#"specified" values will be printed. unspecified values will result in "OK" or "failed"
		self.parent = parent
		for cmd, func in self.hooks.items():
			parent.hook(cmd, func)
			parent.hook("%s.%s" % (self.name, cmd), func)
		for chan, func in self.chanhooks.items():
			parent.hookchan(chan, func)
		for exc, func in self.exceptionhooks:
			parent.hookexception(exc, func)
		for num, func in self.numhooks.items():
			parent.hooknum(num, func)
		for hookdata in self.sockhooks:
			self._create_socket(*hookdata)

		for func, args, kwargs in self.helps:
			try:
				self.mod('help').reghelp(func, *args, **kwargs)
			except:
				pass
		return True
	def modstop(self, parent):
		for cmd, func in self.hooks.items():
			parent.unhook(cmd, func)
			parent.unhook("%s.%s" % (self.name, cmd), func)
		for chan, func in self.chanhooks.items():
			parent.unhookchan(chan, func)
		for exc, func in self.exceptionhooks:
			parent.unhookexception(exc, func)
		for num, func in self.numhooks.items():
			parent.unhooknum(num, func)
		for sock, obj in self.sockets:
			self._destroy_socket(sock, obj)

		for func, args, kwargs in self.helps:
			try:
				self.mod('help').dereghelp(func, *args, **kwargs)
			except:
				pass
		return True

	def hook(self, cmd=None, needchan=True, glevel=ANYONE, clevel=PUBLIC, wantchan=None):
		if wantchan is None: wantchan = needchan
		_cmd = cmd #save this since it gets wiped out...
		def realhook(func):
			cmd = _cmd #...and restore it
			if cmd is None:
				cmd = func.__name__ # default to function name
			if isinstance(cmd, stringbase):
				cmd = (cmd,)

			if clevel > self.PUBLIC and not needchan:
				raise Exception('clevel must be left at default if needchan is False')

			func.needchan = needchan
			func.wantchan = wantchan
			func.reqglevel = glevel
			func.reqclevel = clevel
			func.cmd = cmd
			func.module = func.__module__.split('.')[1]

			for c in cmd:
				self.hooks[c] = func
				if self.parent is not None:
					self.parent.hook(c, func)
					self.parent.hook("%s.%s" % (self.name, c), func)
			return func
		return realhook

	def hookchan(self, chan, glevel=ANYONE, clevel=PUBLIC):
		def realhook(func):
			self.chanhooks[chan] = func
			if self.parent is not None:
				self.parent.hookchan(chan, func)
			return func
		return realhook

	def hookexception(self, exc):
		def realhook(func):
			self.exceptionhooks.append((exc, func))
			if self.parent is not None:
				self.parent.hookexception(exc, func)
			return func
		return realhook

	def hooknum(self, num):
		def realhook(func):
			self.numhooks[str(num)] = func
			if self.parent is not None:
				self.parent.hooknum(str(num), func)
			return func
		return realhook

	def bind(self, bindto, data=None):
		"""Used as a decorator on a class which implements getdata and parse methods.
			See modules/sockets.py for an example.
			Takes an arg like:
			[unix:]/foo/bar
			[udp|tcp:][ip:]port
		"""
		if len(bindto) == 0:
			raise Exception('bindto must have a value')
		if bindto[0] == '/':
			return self._hooksocket(socket.AF_UNIX, socket.SOCK_STREAM, bindto)
		if len(bindto) > 5 and bindto[0:5] == 'unix:':
			return self._hooksocket(socket.AF_UNIX, socket.SOCK_STREAM, bindto[5:])
		af = socket.AF_INET
		ty = socket.SOCK_STREAM
		host = '0.0.0.0'
		if len(bindto) > 4 and bindto[0:4] == 'udp:':
			ty = socket.SOCK_DGRAM
			bindto = bindto[4:]
		if len(bindto) > 4 and bindto[0:4] == 'tcp:':
			bindto = bindto[4:]
		if ':' in bindto:
			pieces = bindto.rsplit(':', 1)
			host = pieces[0]
			bindto = pieces[1]
		port = int(bindto)
		return self._hooksocket(af, ty, (host, port), data)

	def bind_tcp(self, host, port, data=None):
		return self._hooksocket(socket.AF_INET, socket.SOCK_STREAM, (host, port), data)
	def bind_udp(self, host, port, data=None):
		return self._hooksocket(socket.AF_INET, socket.SOCK_DGRAM, (host, port), data)
	def bind_unix(self, path, data=None):
		return self._hooksocket(socket.AF_UNIX, socket.SOCK_STREAM, path, data)
	def _hooksocket(self, af, ty, address, data):
		def realhook(cls):
			if not (hasattr(cls, 'getdata') and callable(cls.getdata)):
				# Check early that the object implements getdata.
				# If getdata ever returns a non-empty list, then a parse method must also exist, but we don't check that.
				raise Exception('Attempted to hook a socket without a class to process data')
			self.sockhooks.append((af, ty, address, cls, data))
			if self.parent is not None:
				self._create_socket(af, ty, address, cls, data)
			return cls
		return realhook
	def _create_socket(self, af, ty, address, cls, data):
		ty = ty | socket.SOCK_NONBLOCK
		sock = socket.socket(af, ty)
		sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
		sock.bind(address)
		obj = _ListenSocket(self, sock, cls, data)
		self.sockets.append((sock,obj))
		sock.listen(5)
		self.parent.newfd(obj, sock.fileno())
		self.parent.log(repr(obj), '?', 'Socket ready to accept new connections (%r, %r, %r, %r)' % (af, ty, address, cls))
	def _destroy_socket(self, sock, obj):
		obj.close()

	def mod(self, modname):
		if self.parent is not None:
			return self.parent.module(modname)
		else:
			return error('unknown parent')


	def flags(self, *flags):
		"""Parses out "flags" to a command, like `MODUNLOAD -AUTOLOAD somemodule`
		@lib.hook()
		@lib.flags('autoload', 'force')
		def baz(bot, user, chan, realtarget, flags, *args)

		Note the added `flags` argument, which will be a dict - in this case `{'autounload':true,'force':false}`."""
		def realhook(func):
			func.flags = [f.lower() for f in flags]

			@wraps(func)
			def parseargs(bot, user, chan, realtarget, *_args):
				args = list(_args) # we need a copy, also need a list, iterate over _args-tuple, mutate args-list
				found_flags = {f: False for f in flags}
				for arg in _args:
					if arg[0] == "-" and len(arg) > 1:
						found_prefix = None
						possible_flag = arg[1:].lower()
						for f in flags:
							if possible_flag == f: # Exact match?
								found_flags[possible_flag] = True
								args.remove(arg)
								found_prefix = None
								break
							elif f.find(possible_flag) == 0: # Is the current word a prefix of a flag?
								if found_prefix is not None: # Is it also a prefix of another flag?
									return 'Error: %s is a prefix of multiple flags (%s, %s).' % (possible_flag, found_prefix[1], f)
								else:
									found_prefix = (arg,f)
						if found_prefix is not None: # found (only one) prefix
							found_flags[found_prefix[1]] = True
							args.remove(found_prefix[0])
				return func(bot, user, chan, realtarget, found_flags, *args)

			return parseargs
		return realhook


	def argsEQ(self, num):
		def realhook(func):
			@wraps(func)
			def checkargs(bot, user, chan, realtarget, *args):
				adjuster = 0
				if hasattr(checkargs, 'flags'):
					adjuster = 1
				if len(args)-adjuster == num:
					return func(bot, user, chan, realtarget, *args)
				else:
					bot.msg(user, self.WRONGARGS)
			return checkargs
		return realhook

	def argsGE(self, num):
		def realhook(func):
			@wraps(func)
			def checkargs(bot, user, chan, realtarget, *args):
				adjuster = 0
				if hasattr(checkargs, 'flags'):
					adjuster = 1
				if len(args)-adjuster >= num:
					return func(bot, user, chan, realtarget, *args)
				else:
					bot.msg(user, self.WRONGARGS)
			return checkargs
		return realhook

	def help(self, *args, **kwargs):
		"""help(syntax, shorthelp, longhelp?, more lines longhelp?, cmd=...?)
		Example:
		help("<user> <pass>", "login")
			^ Help will only be one line. Command name determined based on function name.
		help("<user> <level>", "add a user", cmd=("adduser", "useradd"))
			^ Help will be listed under ADDUSER; USERADD will say "alias for adduser"
		help(None, "do stuff", "This command is really complicated.")
			^ Command takes no args. Short description (in overall HELP listing) is "do stuff".
			Long description (HELP <command>) will say "<command> - do stuff", newline, "This command is really complicated."
		"""
		def realhook(func):
			if self.parent is not None:
				try:
					self.mod('help').reghelp(func, *args, **kwargs)
				except:
					pass
			self.helps.append((func, args, kwargs))
			return func
		return realhook

class _ListenSocket(object):
	def __init__(self, lib, sock, cls, data):
		self.clients = []
		self.lib = lib
		self.sock = sock
		self.cls = cls
		self.data = data

	def _make_closer(self, obj, client):
		def close():
			self.lib.parent.log(repr(self), '?', 'Closing child socket #%d' % (client.fileno()))
			try:
				obj.closing()
			except AttributeError:
				pass
			self.lib.parent.delfd(client.fileno())
			client.shutdown(socket.SHUT_RDWR)
			client.close()
			self.clients.remove((client,obj))
		return close

	def getdata(self):
		client, addr = self.sock.accept()
		obj = self.cls(client, self.data)
		obj.close = self._make_closer(obj, client)
		self.lib.parent.log(repr(self), '?', 'New connection #%d from %s' % (client.fileno(), addr))
		self.clients.append((client,obj))
		self.lib.parent.newfd(obj, client.fileno())
		return []

	def close(self):
		self.lib.parent.log(repr(self), '?', 'Socket closing')
		if self.sock.fileno() != -1:
			self.lib.parent.delfd(self.sock.fileno())
			self.sock.shutdown(socket.SHUT_RDWR)
			self.sock.close()
		for client, obj in self.clients:
			obj.close()

	def __repr__(self): return '<_ListenSocket #%d>' % (self.sock.fileno())