chiark - git - mdw - chopwood/blob - cgi.py

   1 ### -*-python-*-
   2 ###
   3 ### CGI machinery
   4 ###
   5 ### (c) 2013 Mark Wooding
   6 ###
   7
   8 ###----- Licensing notice ---------------------------------------------------
   9 ###
  10 ### This file is part of Chopwood: a password-changing service.
  11 ###
  12 ### Chopwood is free software; you can redistribute it and/or modify
  13 ### it under the terms of the GNU Affero General Public License as
  14 ### published by the Free Software Foundation; either version 3 of the
  15 ### License, or (at your option) any later version.
  16 ###
  17 ### Chopwood is distributed in the hope that it will be useful,
  18 ### but WITHOUT ANY WARRANTY; without even the implied warranty of
  19 ### MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20 ### GNU Affero General Public License for more details.
  21 ###
  22 ### You should have received a copy of the GNU Affero General Public
  23 ### License along with Chopwood; if not, see
  24 ### <http://www.gnu.org/licenses/>.
  25
  26 from __future__ import with_statement
  27
  28 import contextlib as CTX
  29 import os as OS; ENV = OS.environ
  30 import re as RX
  31 import sys as SYS
  32 import time as T
  33 import traceback as TB
  34
  35 from auto import HOME, PACKAGE, VERSION
  36 import config as CONF; CFG = CONF.CFG
  37 import format as F
  38 import output as O; OUT = O.OUT; PRINT = O.PRINT
  39 import subcommand as SC
  40 import util as U
  41
  42 ###--------------------------------------------------------------------------
  43 ### Configuration tweaks.
  44
  45 _script_name = ENV.get('SCRIPT_NAME', '/cgi-bin/chpwd')
  46
  47 CONF.DEFAULTS.update(
  48
  49   ## The URL of this program, when it's run through CGI.
  50   SCRIPT_NAME = _script_name,
  51
  52   ## A (maybe relative) URL for static content.  By default this comes from
  53   ## the main script, but we hope that user agents cache it.
  54   STATIC = _script_name + '/static')
  55
  56 ###--------------------------------------------------------------------------
  57 ### Escaping and encoding.
  58
  59 ## Some handy regular expressions.
  60 R_URLESC = RX.compile('%([0-9a-fA-F]{2})')
  61 R_URLBAD = RX.compile('[^-\\w,.!]')
  62 R_HTMLBAD = RX.compile('[&<>\'"]')
  63
  64 def urldecode(s):
  65   """Decode a single form-url-encoded string S."""
  66   return R_URLESC.sub(lambda m: chr(int(m.group(1), 16)),
  67                       s.replace('+', ' '))
  68   return s
  69
  70 def urlencode(s):
  71   """Encode a single string S using form-url-encoding."""
  72   return R_URLBAD.sub(lambda m: '%%%02x' % ord(m.group(0)), s)
  73
  74 def htmlescape(s):
  75   """Escape a literal string S so that HTML doesn't misinterpret it."""
  76   return R_HTMLBAD.sub(lambda m: '&#x%02x;' % ord(m.group(0)), s)
  77
  78 ## Some standard character sequences, and HTML entity names for prettier
  79 ## versions.
  80 html_quotify = U.StringSubst({
  81   "<": '&lt;',
  82   ">": '&gt;',
  83   "&": '&amp;',
  84   "`": '&lsquo;',
  85   "'": '&rsquo;',
  86   '"': '&quot;',
  87   "``": '&ldquo;',
  88   "''": '&rdquo;',
  89   "--": '&ndash;',
  90   "---": '&mdash;'
  91 })
  92
  93 ###--------------------------------------------------------------------------
  94 ### Output machinery.
  95
  96 class HTTPOutput (O.FileOutput):
  97   """
  98   Output driver providing an automatic HTTP header.
  99
 100   The `headerp' attribute is true if we've written a header.  The `header'
 101   method will print a custom header if this is wanted.
 102   """
 103
 104   def __init__(me, *args, **kw):
 105     """Constructor: initialize `headerp' flag."""
 106     super(HTTPOutput, me).__init__(*args, **kw)
 107     me.headerp = False
 108
 109   def write(me, msg):
 110     """Output protocol: print a header if we've not written one already."""
 111     if not me.headerp: me.header('text/plain')
 112     super(HTTPOutput, me).write(msg)
 113
 114   def header(me, content_type = 'text/plain', **kw):
 115     """
 116     Print a header, if none has yet been printed.
 117
 118     Keyword arguments can be passed to emit HTTP headers: see `http_headers'
 119     for the formatting rules.
 120     """
 121     if me.headerp: return
 122     me.headerp = True
 123     for h in O.http_headers(content_type = content_type, **kw):
 124       me.writeln(h)
 125     me.writeln('')
 126     if METHOD == 'HEAD':
 127       HEADER_DONE()
 128
 129 def cookie(name, value, **kw):
 130   """
 131   Return a HTTP `Set-Cookie' header.
 132
 133   The NAME and VALUE give the name and value of the cookie; both are
 134   form-url-encoded to prevent misinterpretation (fortunately, `cgiparse'
 135   knows to undo this transformation).  The KW are other attributes to
 136   declare: the names are forced to lower-case and underscores `_' are
 137   replaced by hyphens `-'; a `True' value is assumed to indicate that the
 138   attribute is boolean, and omitted.
 139   """
 140   attr = {}
 141   for k, v in kw.iteritems():
 142     k = '-'.join(i.lower() for i in k.split('_'))
 143     attr[k] = v
 144   try: maxage = int(attr['max-age'])
 145   except KeyError: pass
 146   else:
 147     attr['expires'] = T.strftime('%a, %d %b %Y %H:%M:%S GMT',
 148                                  T.gmtime(U.NOW + maxage))
 149   return '; '.join(['%s=%s' % (urlencode(name), urlencode(value))] +
 150                    [v is not True and '%s=%s' % (k, v) or k
 151                     for k, v in attr.iteritems() if v])
 152
 153 def action(*v, **kw):
 154   """
 155   Build a URL invoking this script.
 156
 157   The positional arguments V are used to construct a path which is appended
 158   to the (deduced or configured) script name (and presumably will be read
 159   back as `PATH_INFO').  The keyword arguments are (form-url-encoded and)
 160   appended as a query string, if present.
 161   """
 162   url = '/'.join([CFG.SCRIPT_NAME] + list(v))
 163   if kw:
 164     url += '?' + ';'.join('%s=%s' % (urlencode(k), urlencode(kw[k]))
 165                           for k in sorted(kw))
 166   return htmlescape(url)
 167
 168 def static(name):
 169   """Build a URL for the static file NAME."""
 170   return htmlescape(CFG.STATIC + '/' + name)
 171
 172 def redirect(where, **kw):
 173   """
 174   Write a complete redirection to some other URL.
 175   """
 176   OUT.header(content_type = 'text/html',
 177              status = 302, location = where,
 178              **kw)
 179   PRINT("""\
 180 <html>
 181 <head><title>No, sorry, it's moved again.</title></head>
 182 <body><p>I'm <a href="%s">over here</a> now.<body>
 183 </html>""" % htmlescape(where))
 184
 185 ###--------------------------------------------------------------------------
 186 ### Templates.
 187
 188 ## Where we find our templates.
 189 TMPLDIR = HOME
 190
 191 ## Keyword arguments for templates.
 192 STATE = U.Fluid()
 193 STATE.kw = {}
 194
 195 ## Set some basic keyword arguments.
 196 @CONF.hook
 197 def set_template_keywords():
 198   STATE.kw.update(
 199     package = PACKAGE,
 200     version = VERSION,
 201     script = CFG.SCRIPT_NAME,
 202     static = CFG.STATIC,
 203     allowop = CFG.ALLOWOP)
 204
 205 class TemplateFinder (object):
 206   """
 207   A magical fake dictionary whose keys are templates.
 208   """
 209   def __init__(me, dir):
 210     me._cache = {}
 211     me._dir = dir
 212   def __getitem__(me, key):
 213     try: return me._cache[key]
 214     except KeyError: pass
 215     with open(OS.path.join(me._dir, key)) as f: tmpl = f.read()
 216     me._cache[key] = tmpl
 217     return tmpl
 218 STATE.kw['TMPL'] = TMPL = TemplateFinder(TMPLDIR)
 219
 220 @CTX.contextmanager
 221 def tmplkw(**kw):
 222   """
 223   Context manager: execute the body with additional keyword arguments
 224   """
 225   d = dict()
 226   d.update(STATE.kw)
 227   d.update(kw)
 228   with STATE.bind(kw = d): yield
 229
 230 FORMATOPS = {}
 231
 232 class FormatHTML (F.SimpleFormatOperation):
 233   """
 234   ~H: escape output suitable for inclusion in HTML.
 235
 236   With `:', additionally apply quotification.
 237   """
 238   def _convert(me, arg):
 239     if me.colonp: return html_quotify(arg)
 240     else: return htmlescape(arg)
 241 FORMATOPS['H'] = FormatHTML
 242
 243 class FormatWrap (F.BaseFormatOperation):
 244   """
 245   ~<...~@>: wrap enclosed material in another formatting control string.
 246
 247   The argument is a formatting control.  The enclosed material is split into
 248   pieces separated by `~;' markers.  The formatting control is performed, and
 249   passed the list of pieces (as compiled formatting operations) in the
 250   keyword argument `wrapped'.
 251   """
 252   def __init__(me, *args):
 253     super(FormatWrap, me).__init__(*args)
 254     pieces = []
 255     while True:
 256       piece, delim = F.collect_subformat('>;')
 257       pieces.append(piece)
 258       if delim.char == '>': break
 259     me.pieces = pieces
 260   def _format(me, atp, colonp):
 261     op = F.compile(me.getarg.get())
 262     with F.FORMAT.bind(argmap = dict(F.FORMAT.argmap, wrapped = me.pieces)):
 263       op.format()
 264 FORMATOPS['<'] = FormatWrap
 265
 266 def format_tmpl(control, **kw):
 267   with F.COMPILE.bind(opmaps = [FORMATOPS, F.BASEOPS]):
 268     with tmplkw(**kw):
 269       F.format(OUT, control, **STATE.kw)
 270
 271 def page(template, header = {}, title = 'Chopwood', **kw):
 272   header = dict(header, content_type = 'text/html')
 273   OUT.header(**header)
 274   format_tmpl(TMPL['wrapper.fhtml'],
 275               title = title, payload = TMPL[template], **kw)
 276
 277 ###--------------------------------------------------------------------------
 278 ### Error reporting.
 279
 280 @CTX.contextmanager
 281 def cgi_errors(hook = None):
 282   """
 283   Context manager: report errors in the body as useful HTML.
 284
 285   If HOOK is given, then call it before reporting errors.  It may have set up
 286   useful stuff.
 287   """
 288   try:
 289     yield None
 290   except Exception, e:
 291     if hook: hook()
 292     if isinstance(e, U.ExpectedError) and not OUT.headerp:
 293       page('error.fhtml',
 294            header = dict(status = e.code),
 295            title = 'Chopwood: error', error = e)
 296     else:
 297       exty, exval, extb = SYS.exc_info()
 298       with tmplkw(exception = TB.format_exception_only(exty, exval),
 299                   traceback = TB.extract_tb(extb),
 300                   PARAM = sorted(PARAM),
 301                   COOKIE = sorted(COOKIE.items()),
 302                   PATH = PATH,
 303                   ENV = sorted(ENV.items())):
 304         if OUT.headerp:
 305           format_tmpl(TMPL['exception.fhtml'], toplevel = False)
 306         else:
 307           page('exception.fhtml',
 308                header = dict(status = 500),
 309                title = 'Chopwood: internal error',
 310                toplevel = True)
 311
 312 ###--------------------------------------------------------------------------
 313 ### CGI input.
 314
 315 ## Lots of global variables to be filled in by `cgiparse'.
 316 METHOD = None
 317 COOKIE = {}
 318 SPECIAL = {}
 319 PARAM = []
 320 PARAMDICT = {}
 321 PATH = []
 322 SSLP = False
 323 HEADER_DONE = lambda: None
 324
 325 ## Regular expressions for splitting apart query and cookie strings.
 326 R_QSPLIT = RX.compile('[;&]')
 327 R_CSPLIT = RX.compile(';')
 328
 329 def split_keyvalue(string, delim, default):
 330   """
 331   Split a STRING, and generate the resulting KEY=VALUE pairs.
 332
 333   The string is split at DELIM; the components are parsed into KEY[=VALUE]
 334   pairs.  The KEYs and VALUEs are stripped of leading and trailing
 335   whitespace, and form-url-decoded.  If the VALUE is omitted, then the
 336   DEFAULT is used unless the DEFAULT is `None' in which case the component is
 337   simply ignored.
 338   """
 339   for kv in delim.split(string):
 340     try:
 341       k, v = kv.split('=', 1)
 342     except ValueError:
 343       if default is None: continue
 344       else: k, v = kv, default
 345     k, v = k.strip(), v.strip()
 346     if not k: continue
 347     k, v = urldecode(k), urldecode(v)
 348     yield k, v
 349
 350 def cgiparse():
 351   """
 352   Process all of the various exciting CGI environment variables.
 353
 354   We read environment variables and populate some tables left in global
 355   variables: it's all rather old-school.  Variables set are as follows.
 356
 357   `COOKIE'
 358         A dictionary mapping cookie names to the values provided by the user
 359         agent.
 360
 361   `SPECIAL'
 362         A dictionary holding some special query parameters which are of
 363         interest at a global level, and should not be passed to a subcommand
 364         handler.  No new entries will be added to this dictionary, though
 365         values will be modified to reflect the query parameters discovered.
 366         Conventionally, such parameters have names beginning with `%'.
 367
 368   `PARAM'
 369         The query parameters as a list of (KEY, VALUE) pairs.  Special
 370         parameters are omitted.
 371
 372   `PARAMDICT'
 373         The query parameters as a dictionary.  Special parameters, and
 374         parameters which appear more than once, are omitted.
 375
 376   `PATH'
 377         The trailing `PATH_INFO' path, split at `/' markers, with any
 378         trailing empty component removed.
 379
 380   `SSLP'
 381         True if the client connection is carried over SSL or TLS.
 382   """
 383
 384   global METHOD, SSLP
 385
 386   def getenv(var):
 387     try: return ENV[var]
 388     except KeyError: raise U.ExpectedError, (500, "No `%s' supplied" % var)
 389
 390   ## Yes, we want the request method.
 391   METHOD = getenv('REQUEST_METHOD')
 392
 393   ## Acquire the query string.
 394   if METHOD in ['GET', 'HEAD']:
 395     q = getenv('QUERY_STRING')
 396
 397   elif METHOD == 'POST':
 398
 399     ## We must read the query string from stdin.
 400     n = getenv('CONTENT_LENGTH')
 401     if not n.isdigit():
 402       raise U.ExpectedError, (500, "Invalid CONTENT_LENGTH")
 403     n = int(n, 10)
 404     if getenv('CONTENT_TYPE') != 'application/x-www-form-urlencoded':
 405       raise U.ExpectedError, (500, "Unexpected content type `%s'" % ct)
 406     q = SYS.stdin.read(n)
 407     if len(q) != n:
 408       raise U.ExpectedError, (500, "Failed to read correct length")
 409
 410   else:
 411     raise U.ExpectedError, (500, "Unexpected request method `%s'" % METHOD)
 412
 413   ## Populate the `SPECIAL', `PARAM' and `PARAMDICT' tables.
 414   seen = set()
 415   for k, v in split_keyvalue(q, R_QSPLIT, 't'):
 416     if k in SPECIAL:
 417       SPECIAL[k] = v
 418     else:
 419       PARAM.append((k, v))
 420       if k in seen:
 421         del PARAMDICT[k]
 422       else:
 423         PARAMDICT[k] = v
 424         seen.add(k)
 425
 426   ## Parse out the cookies, if any.
 427   try: c = ENV['HTTP_COOKIE']
 428   except KeyError: pass
 429   else:
 430     for k, v in split_keyvalue(c, R_CSPLIT, None): COOKIE[k] = v
 431
 432   ## Set up the `PATH'.
 433   try: p = ENV['PATH_INFO']
 434   except KeyError: pass
 435   else:
 436     pp = p.lstrip('/').split('/')
 437     if pp and not pp[-1]: pp.pop()
 438     PATH[:] = pp
 439
 440   ## Check the crypto for the connection.
 441   if ENV.get('SSL_PROTOCOL'):
 442     SSLP = True
 443
 444 ###--------------------------------------------------------------------------
 445 ### CGI subcommands.
 446
 447 class Subcommand (SC.Subcommand):
 448   """
 449   A CGI subcommand object.
 450
 451   As for `subcommand.Subcommand', but with additional protocol for processing
 452   CGI parameters.
 453   """
 454
 455   def cgi(me, param, path):
 456     """
 457     Invoke the subcommand given a collection of CGI parameters.
 458
 459     PARAM is a list of (KEY, VALUE) pairs from the CGI query.  The CGI query
 460     parameters are checked against the subcommand's parameters (making sure
 461     that mandatory parameters are supplied, that any switches are given
 462     boolean values, and that only the `rest' parameter, if any, is
 463     duplicated).
 464
 465     PATH is a list of trailing path components.  They are used to satisfy the
 466     `rest' parameter if there is one and there are no query parameters which
 467     satisfy the `rest' parameter; otherwise, an `ExpectedError' is raised if
 468     the list of path elements is non-empty.
 469     """
 470
 471     global HEADER_DONE
 472
 473     ## We're going to make a pass over the supplied parameters, and we'll
 474     ## check them off against the formal parameters as we go; so we'll need
 475     ## to be able to look them up.  We'll also keep track of the ones we've
 476     ## seen so that we can make sure that all of the mandatory parameters
 477     ## were actually supplied.
 478     ##
 479     ## To that end: `want' is a dictionary mapping parameter names to
 480     ## functions which will do something useful with the value; `seen' is a
 481     ## set of the parameters which have been assigned; and `kw' is going to
 482     ## be the keyword-argument dictionary we pass to the handler function.
 483     want = {}
 484     kw = {}
 485
 486     def set_value(k, v):
 487       """Set a simple value: we shouldn't see multiple values."""
 488       if k in kw:
 489         raise U.ExpectedError, (400, "Repeated parameter `%s'" % k)
 490       kw[k] = v
 491     def set_bool(k, v):
 492       """Set a simple boolean value: for switches."""
 493       set_value(k, v.lower() in ['true', 't', 'yes', 'y'])
 494     def set_list(k, v):
 495       """Append the value to a list: for the `rest' parameter."""
 496       kw.setdefault(k, []).append(v)
 497
 498     ## Set up the `want' map.
 499     for o in me.opts:
 500       if o.argname: want[o.name] = set_value
 501       else: want[o.name] = set_bool
 502     for p in me.params: want[p.name] = set_value
 503     for p in me.oparams: want[p.name] = set_value
 504     if me.rparam: want[me.rparam.name] = set_list
 505
 506     ## Work through the list of supplied parameters.
 507     for k, v in param:
 508       try:
 509         f = want[k]
 510       except KeyError:
 511         if v:
 512           raise U.ExpectedError, (400, "Unexpected parameter `%s'" % k)
 513       else:
 514         f(k, v)
 515
 516     ## Deal with a path, if there is one.
 517     if path:
 518       if me.rparam and me.rparam.name not in kw:
 519         kw[me.rparam.name] = path
 520       else:
 521         raise U.ExpectedError, (404, "Superfluous path elements")
 522
 523     ## Make sure we saw all of the mandatory parameters.
 524     for p in me.params:
 525       if p.name not in kw:
 526         raise U.ExpectedError, (400, "Missing parameter `%s'" % p.name)
 527
 528     ## Invoke the subcommand.
 529     me.func(**kw)
 530
 531 def subcommand(name, contexts, desc, cls = Subcommand, *args, **kw):
 532   """Decorator for defining CGI subcommands."""
 533   return SC.subcommand(name, contexts, desc, cls = cls, *args, **kw)
 534
 535 ###----- That's all, folks --------------------------------------------------