Documentation + cleaning up a little.
authorEric Price <ecprice@mit.edu>
Mon, 8 Oct 2007 11:17:34 +0000 (07:17 -0400)
committerEric Price <ecprice@mit.edu>
Mon, 8 Oct 2007 11:17:34 +0000 (07:17 -0400)
svn path=/trunk/web/; revision=145

templates/main.py

index c997710..152cd75 100755 (executable)
@@ -21,9 +21,26 @@ from sipb_xen_database import *
 import random
 
 class MyException(Exception):
 import random
 
 class MyException(Exception):
+    """Base class for my exceptions"""
     pass
 
     pass
 
+class InvalidInput(MyException):
+    """Exception for user-provided input is invalid but maybe in good faith.
+
+    This would include setting memory to negative (which might be a
+    typo) but not setting an invalid boot CD (which requires bypassing
+    the select box).
+    """
+    pass
+
+class CodeError(MyException):
+    """Exception for internal errors or bad faith input."""
+    pass
+
+
+
 def helppopup(subj):
 def helppopup(subj):
+    """Return HTML code for a (?) link to a specified help topic"""
     return '<span class="helplink"><a href="help?subject='+subj+'&amp;simple=true" target="_blank" onclick="return helppopup(\''+subj+'\')">(?)</a></span>'
 
 
     return '<span class="helplink"><a href="help?subject='+subj+'&amp;simple=true" target="_blank" onclick="return helppopup(\''+subj+'\')">(?)</a></span>'
 
 
@@ -38,6 +55,7 @@ def randomUUID():
     return [ random.randint(0, 255) for _ in range(0, 16) ]
 
 def uuidToString(u):
     return [ random.randint(0, 255) for _ in range(0, 16) ]
 
 def uuidToString(u):
+    """Turn a numeric UUID to a hyphen-seperated one."""
     return "-".join(["%02x" * 4, "%02x" * 2, "%02x" * 2, "%02x" * 2,
                      "%02x" * 6]) % tuple(u)
 
     return "-".join(["%02x" * 4, "%02x" * 2, "%02x" * 2, "%02x" * 2,
                      "%02x" * 6]) % tuple(u)
 
@@ -50,11 +68,21 @@ MIN_DISK_SINGLE = 0.1
 MAX_VMS_TOTAL = 10
 MAX_VMS_ACTIVE = 4
 
 MAX_VMS_TOTAL = 10
 MAX_VMS_ACTIVE = 4
 
-def getMachinesOwner(owner):
+def getMachinesByOwner(owner):
+    """Return the machines owned by a given owner."""
     return Machine.select_by(owner=owner)
 
 def maxMemory(user, machine=None, on=None):
     return Machine.select_by(owner=owner)
 
 def maxMemory(user, machine=None, on=None):
-    machines = getMachinesOwner(user.username)
+    """Return the maximum memory for a machine or a user.
+
+    If machine is None, return the memory available for a new 
+    machine.  Else, return the maximum that machine can have.
+
+    on is a dictionary from machines to booleans, whether a machine is
+    on.  If None, it is recomputed. XXX make this global?
+    """
+
+    machines = getMachinesByOwner(user.username)
     if on is None:
         on = getUptimes(machines)
     active_machines = [x for x in machines if on[x]]
     if on is None:
         on = getUptimes(machines)
     active_machines = [x for x in machines if on[x]]
@@ -62,13 +90,13 @@ def maxMemory(user, machine=None, on=None):
     return min(MAX_MEMORY_SINGLE, MAX_MEMORY_TOTAL-mem_usage)
 
 def maxDisk(user, machine=None):
     return min(MAX_MEMORY_SINGLE, MAX_MEMORY_TOTAL-mem_usage)
 
 def maxDisk(user, machine=None):
-    machines = getMachinesOwner(user.username)
+    machines = getMachinesByOwner(user.username)
     disk_usage = sum([sum([y.size for y in x.disks])
                       for x in machines if x != machine])
     return min(MAX_DISK_SINGLE, MAX_DISK_TOTAL-disk_usage/1024.)
 
 def canAddVm(user, on=None):
     disk_usage = sum([sum([y.size for y in x.disks])
                       for x in machines if x != machine])
     return min(MAX_DISK_SINGLE, MAX_DISK_TOTAL-disk_usage/1024.)
 
 def canAddVm(user, on=None):
-    machines = getMachinesOwner(user.username)
+    machines = getMachinesByOwner(user.username)
     if on is None:
         on = getUptimes(machines)
     active_machines = [x for x in machines if on[x]]
     if on is None:
         on = getUptimes(machines)
     active_machines = [x for x in machines if on[x]]
@@ -76,11 +104,13 @@ def canAddVm(user, on=None):
             len(active_machines) < MAX_VMS_ACTIVE)
 
 def haveAccess(user, machine):
             len(active_machines) < MAX_VMS_ACTIVE)
 
 def haveAccess(user, machine):
+    """Return whether a user has access to a machine"""
     if user.username == 'moo':
         return True
     return machine.owner == user.username
 
 def error(op, user, fields, err):
     if user.username == 'moo':
         return True
     return machine.owner == user.username
 
 def error(op, user, fields, err):
+    """Print an error page when a CodeError occurs"""
     d = dict(op=op, user=user, errorMessage=str(err))
     print Template(file='error.tmpl', searchList=[d, global_dict]);
 
     d = dict(op=op, user=user, errorMessage=str(err))
     print Template(file='error.tmpl', searchList=[d, global_dict]);
 
@@ -103,7 +133,7 @@ def kinit(username = 'tabbott/extra', keytab = '/etc/tabbott.keytab'):
                          stderr=subprocess.PIPE)
     e = p.wait()
     if e:
                          stderr=subprocess.PIPE)
     e = p.wait()
     if e:
-        raise MyException("Error %s in kinit: %s" % (e, p.stderr.read()))
+        raise CodeError("Error %s in kinit: %s" % (e, p.stderr.read()))
 
 def checkKinit():
     """If we lack tickets, kinit."""
 
 def checkKinit():
     """If we lack tickets, kinit."""
@@ -125,7 +155,7 @@ def remctl(*args, **kws):
         p.wait()
         return p.stdout.read(), p.stderr.read()
     if p.wait():
         p.wait()
         return p.stdout.read(), p.stderr.read()
     if p.wait():
-        raise MyException('ERROR on remctl %s: %s' %
+        raise CodeError('ERROR on remctl %s: %s' %
                           (args, p.stderr.read()))
     return p.stdout.read()
 
                           (args, p.stderr.read()))
     return p.stdout.read()
 
@@ -199,11 +229,11 @@ def statusInfo(machine):
     """
     value_string, err_string = remctl('list-long', machine.name, err=True)
     if 'Unknown command' in err_string:
     """
     value_string, err_string = remctl('list-long', machine.name, err=True)
     if 'Unknown command' in err_string:
-        raise MyException("ERROR in remctl list-long %s is not registered" % (machine.name,))
+        raise CodeError("ERROR in remctl list-long %s is not registered" % (machine.name,))
     elif 'does not exist' in err_string:
         return None
     elif err_string:
     elif 'does not exist' in err_string:
         return None
     elif err_string:
-        raise MyException("ERROR in remctl list-long %s:  %s" % (machine.name, err_string))
+        raise CodeError("ERROR in remctl list-long %s:  %s" % (machine.name, err_string))
     status = parseStatus(value_string)
     return status
 
     status = parseStatus(value_string)
     return status
 
@@ -223,11 +253,11 @@ def createVm(user, name, memory, disk, is_hvm, cdrom):
     transaction = ctx.current.create_transaction()
     try:
         if memory > maxMemory(user):
     transaction = ctx.current.create_transaction()
     try:
         if memory > maxMemory(user):
-            raise MyException("Too much memory requested")
+            raise InvalidInput("Too much memory requested")
         if disk > maxDisk(user) * 1024:
         if disk > maxDisk(user) * 1024:
-            raise MyException("Too much disk requested")
+            raise InvalidInput("Too much disk requested")
         if not canAddVm(user):
         if not canAddVm(user):
-            raise MyException("Too many VMs requested")
+            raise InvalidInput("Too many VMs requested")
         res = meta.engine.execute('select nextval(\'"machines_machine_id_seq"\')')
         id = res.fetchone()[0]
         machine = Machine()
         res = meta.engine.execute('select nextval(\'"machines_machine_id_seq"\')')
         id = res.fetchone()[0]
         machine = Machine()
@@ -245,7 +275,7 @@ def createVm(user, name, memory, disk, is_hvm, cdrom):
                     'hda', disk)
         open = NIC.select_by(machine_id=None)
         if not open: #No IPs left!
                     'hda', disk)
         open = NIC.select_by(machine_id=None)
         if not open: #No IPs left!
-            return "No IP addresses left!  Contact sipb-xen-dev@mit.edu"
+            raise CodeError("No IP addresses left!  Contact sipb-xen-dev@mit.edu")
         nic = open[0]
         nic.machine_id = machine.machine_id
         nic.hostname = name
         nic = open[0]
         nic.machine_id = machine.machine_id
         nic.hostname = name
@@ -263,38 +293,41 @@ def createVm(user, name, memory, disk, is_hvm, cdrom):
     return machine
 
 def validMemory(user, memory, machine=None):
     return machine
 
 def validMemory(user, memory, machine=None):
+    """Parse and validate limits for memory for a given user and machine."""
     try:
         memory = int(memory)
         if memory < MIN_MEMORY_SINGLE:
             raise ValueError
     except ValueError:
     try:
         memory = int(memory)
         if memory < MIN_MEMORY_SINGLE:
             raise ValueError
     except ValueError:
-        raise MyException("Invalid memory amount; must be at least %s MB" %
+        raise InvalidInput("Invalid memory amount; must be at least %s MB" %
                           MIN_MEMORY_SINGLE)
     if memory > maxMemory(user, machine):
                           MIN_MEMORY_SINGLE)
     if memory > maxMemory(user, machine):
-        raise MyException("Too much memory requested")
+        raise InvalidInput("Too much memory requested")
     return memory
 
 def validDisk(user, disk, machine=None):
     return memory
 
 def validDisk(user, disk, machine=None):
+    """Parse and validate limits for disk for a given user and machine."""
     try:
         disk = float(disk)
         if disk > maxDisk(user, machine):
     try:
         disk = float(disk)
         if disk > maxDisk(user, machine):
-            raise MyException("Too much disk requested")
+            raise InvalidInput("Too much disk requested")
         disk = int(disk * 1024)
         if disk < MIN_DISK_SINGLE * 1024:
             raise ValueError
     except ValueError:
         disk = int(disk * 1024)
         if disk < MIN_DISK_SINGLE * 1024:
             raise ValueError
     except ValueError:
-        raise MyException("Invalid disk amount; minimum is %s GB" %
+        raise InvalidInput("Invalid disk amount; minimum is %s GB" %
                           MIN_DISK_SINGLE)
     return disk
 
 def create(user, fields):
                           MIN_DISK_SINGLE)
     return disk
 
 def create(user, fields):
+    """Handler for create requests."""
     name = fields.getfirst('name')
     if not validMachineName(name):
     name = fields.getfirst('name')
     if not validMachineName(name):
-        raise MyException("Invalid name '%s'" % name)
+        raise InvalidInput("Invalid name '%s'" % name)
     name = user.username + '_' + name.lower()
 
     if Machine.get_by(name=name):
     name = user.username + '_' + name.lower()
 
     if Machine.get_by(name=name):
-        raise MyException("A machine named '%s' already exists" % name)
+        raise InvalidInput("A machine named '%s' already exists" % name)
     
     memory = fields.getfirst('memory')
     memory = validMemory(user, memory)
     
     memory = fields.getfirst('memory')
     memory = validMemory(user, memory)
@@ -304,22 +337,21 @@ def create(user, fields):
 
     vm_type = fields.getfirst('vmtype')
     if vm_type not in ('hvm', 'paravm'):
 
     vm_type = fields.getfirst('vmtype')
     if vm_type not in ('hvm', 'paravm'):
-        raise MyException("Invalid vm type '%s'"  % vm_type)    
+        raise CodeError("Invalid vm type '%s'"  % vm_type)    
     is_hvm = (vm_type == 'hvm')
 
     cdrom = fields.getfirst('cdrom')
     if cdrom is not None and not CDROM.get(cdrom):
     is_hvm = (vm_type == 'hvm')
 
     cdrom = fields.getfirst('cdrom')
     if cdrom is not None and not CDROM.get(cdrom):
-        raise MyException("Invalid cdrom type '%s'" % cdrom)    
+        raise CodeError("Invalid cdrom type '%s'" % cdrom)    
     
     machine = createVm(user, name, memory, disk, is_hvm, cdrom)
     
     machine = createVm(user, name, memory, disk, is_hvm, cdrom)
-    if isinstance(machine, basestring):
-        raise MyException(machine)
     d = dict(user=user,
              machine=machine)
     print Template(file='create.tmpl',
                    searchList=[d, global_dict]);
 
 def listVms(user, fields):
     d = dict(user=user,
              machine=machine)
     print Template(file='create.tmpl',
                    searchList=[d, global_dict]);
 
 def listVms(user, fields):
+    """Handler for list requests."""
     machines = [m for m in Machine.select() if haveAccess(user, m)]    
     on = {}
     has_vnc = {}
     machines = [m for m in Machine.select() if haveAccess(user, m)]    
     on = {}
     has_vnc = {}
@@ -351,17 +383,21 @@ def listVms(user, fields):
     print Template(file='list.tmpl', searchList=[d, global_dict])
 
 def testMachineId(user, machineId, exists=True):
     print Template(file='list.tmpl', searchList=[d, global_dict])
 
 def testMachineId(user, machineId, exists=True):
+    """Parse, validate and check authorization for a given machineId.
+
+    If exists is False, don't check that it exists.
+    """
     if machineId is None:
     if machineId is None:
-        raise MyException("No machine ID specified")
+        raise CodeError("No machine ID specified")
     try:
         machineId = int(machineId)
     except ValueError:
     try:
         machineId = int(machineId)
     except ValueError:
-        raise MyException("Invalid machine ID '%s'" % machineId)
+        raise CodeError("Invalid machine ID '%s'" % machineId)
     machine = Machine.get(machineId)
     if exists and machine is None:
     machine = Machine.get(machineId)
     if exists and machine is None:
-        raise MyException("No such machine ID '%s'" % machineId)
-    if not haveAccess(user, machine):
-        raise MyException("No access to machine ID '%s'" % machineId)
+        raise CodeError("No such machine ID '%s'" % machineId)
+    if machine is not None and not haveAccess(user, machine):
+        raise CodeError("No access to machine ID '%s'" % machineId)
     return machine
 
 def vnc(user, fields):
     return machine
 
 def vnc(user, fields):
@@ -377,9 +413,11 @@ def vnc(user, fields):
     -t nat -A PREROUTING -s ! 18.181.0.60 -i eth1 -p tcp -m tcp --dport 10003 -j DNAT --to-destination 18.181.0.60:10003 
     -t nat -A POSTROUTING -d 18.181.0.60 -o eth1 -p tcp -m tcp --dport 10003 -j SNAT --to-source 18.187.7.142 
     -A FORWARD -d 18.181.0.60 -i eth1 -o eth1 -p tcp -m tcp --dport 10003 -j ACCEPT
     -t nat -A PREROUTING -s ! 18.181.0.60 -i eth1 -p tcp -m tcp --dport 10003 -j DNAT --to-destination 18.181.0.60:10003 
     -t nat -A POSTROUTING -d 18.181.0.60 -o eth1 -p tcp -m tcp --dport 10003 -j SNAT --to-source 18.187.7.142 
     -A FORWARD -d 18.181.0.60 -i eth1 -o eth1 -p tcp -m tcp --dport 10003 -j ACCEPT
+
+    Remember to enable iptables!
+    echo 1 > /proc/sys/net/ipv4/ip_forward
     """
     machine = testMachineId(user, fields.getfirst('machine_id'))
     """
     machine = testMachineId(user, fields.getfirst('machine_id'))
-    #XXX fix
     
     TOKEN_KEY = "0M6W0U1IXexThi5idy8mnkqPKEq1LtEnlK/pZSn0cDrN"
 
     
     TOKEN_KEY = "0M6W0U1IXexThi5idy8mnkqPKEq1LtEnlK/pZSn0cDrN"
 
@@ -402,6 +440,11 @@ def vnc(user, fields):
                    searchList=[d, global_dict])
 
 def getNicInfo(data_dict, machine):
                    searchList=[d, global_dict])
 
 def getNicInfo(data_dict, machine):
+    """Helper function for info, get data on nics for a machine.
+
+    Modifies data_dict to include the relevant data, and returns a list
+    of (key, name) pairs to display "name: data_dict[key]" to the user.
+    """
     data_dict['num_nics'] = len(machine.nics)
     nic_fields_template = [('nic%s_hostname', 'NIC %s hostname'),
                            ('nic%s_mac', 'NIC %s MAC Addr'),
     data_dict['num_nics'] = len(machine.nics)
     nic_fields_template = [('nic%s_hostname', 'NIC %s hostname'),
                            ('nic%s_mac', 'NIC %s MAC Addr'),
@@ -418,6 +461,11 @@ def getNicInfo(data_dict, machine):
     return nic_fields
 
 def getDiskInfo(data_dict, machine):
     return nic_fields
 
 def getDiskInfo(data_dict, machine):
+    """Helper function for info, get data on disks for a machine.
+
+    Modifies data_dict to include the relevant data, and returns a list
+    of (key, name) pairs to display "name: data_dict[key]" to the user.
+    """
     data_dict['num_disks'] = len(machine.disks)
     disk_fields_template = [('%s_size', '%s size')]
     disk_fields = []
     data_dict['num_disks'] = len(machine.disks)
     disk_fields_template = [('%s_size', '%s size')]
     disk_fields = []
@@ -428,6 +476,7 @@ def getDiskInfo(data_dict, machine):
     return disk_fields
 
 def deleteVM(machine):
     return disk_fields
 
 def deleteVM(machine):
+    """Delete a VM."""
     transaction = ctx.current.create_transaction()
     delete_disk_pairs = [(machine.name, d.guest_device_name) for d in machine.disks]
     try:
     transaction = ctx.current.create_transaction()
     delete_disk_pairs = [(machine.name, d.guest_device_name) for d in machine.disks]
     try:
@@ -447,15 +496,16 @@ def deleteVM(machine):
     unregisterMachine(machine)
 
 def command(user, fields):
     unregisterMachine(machine)
 
 def command(user, fields):
+    """Handler for running commands like boot and delete on a VM."""
     print time.time()-start_time
     machine = testMachineId(user, fields.getfirst('machine_id'))
     action = fields.getfirst('action')
     cdrom = fields.getfirst('cdrom')
     print time.time()-start_time
     if cdrom is not None and not CDROM.get(cdrom):
     print time.time()-start_time
     machine = testMachineId(user, fields.getfirst('machine_id'))
     action = fields.getfirst('action')
     cdrom = fields.getfirst('cdrom')
     print time.time()-start_time
     if cdrom is not None and not CDROM.get(cdrom):
-        raise MyException("Invalid cdrom type '%s'" % cdrom)    
+        raise CodeError("Invalid cdrom type '%s'" % cdrom)    
     if action not in ('Reboot', 'Power on', 'Power off', 'Shutdown', 'Delete VM'):
     if action not in ('Reboot', 'Power on', 'Power off', 'Shutdown', 'Delete VM'):
-        raise MyException("Invalid action '%s'" % action)
+        raise CodeError("Invalid action '%s'" % action)
     if action == 'Reboot':
         if cdrom is not None:
             remctl('reboot', machine.name, cdrom)
     if action == 'Reboot':
         if cdrom is not None:
             remctl('reboot', machine.name, cdrom)
@@ -463,7 +513,7 @@ def command(user, fields):
             remctl('reboot', machine.name)
     elif action == 'Power on':
         if maxMemory(user) < machine.memory:
             remctl('reboot', machine.name)
     elif action == 'Power on':
         if maxMemory(user) < machine.memory:
-            raise MyException("You don't have enough free RAM quota")
+            raise InvalidInput("You don't have enough free RAM quota")
         bootMachine(machine, cdrom)
     elif action == 'Power off':
         remctl('destroy', machine.name)
         bootMachine(machine, cdrom)
     elif action == 'Power off':
         remctl('destroy', machine.name)
@@ -479,9 +529,12 @@ def command(user, fields):
     print Template(file="command.tmpl", searchList=[d, global_dict])
         
 def modify(user, fields):
     print Template(file="command.tmpl", searchList=[d, global_dict])
         
 def modify(user, fields):
+    """Handler for modifying attributes of a machine."""
+    #XXX not written yet
     machine = testMachineId(user, fields.getfirst('machine_id'))
     
 def help(user, fields):
     machine = testMachineId(user, fields.getfirst('machine_id'))
     
 def help(user, fields):
+    """Handler for help messages."""
     simple = fields.getfirst('simple')
     subjects = fields.getlist('subject')
     
     simple = fields.getfirst('simple')
     subjects = fields.getlist('subject')
     
@@ -504,6 +557,7 @@ want an HVM virtualized machine.""",
     
 
 def info(user, fields):
     
 
 def info(user, fields):
+    """Handler for info on a single VM."""
     machine = testMachineId(user, fields.getfirst('machine_id'))
     status = statusInfo(machine)
     has_vnc = hasVnc(status)
     machine = testMachineId(user, fields.getfirst('machine_id'))
     status = statusInfo(machine)
     has_vnc = hasVnc(status)
@@ -621,5 +675,7 @@ if __name__ == '__main__':
         connect('postgres://sipb-xen@sipb-xen-dev/sipb_xen')
     try:
         fun(u, fields)
         connect('postgres://sipb-xen@sipb-xen-dev/sipb_xen')
     try:
         fun(u, fields)
-    except MyException, err:
+    except CodeError, err:
+        error(operation, u, fields, err)
+    except InvalidInput, err:
         error(operation, u, fields, err)
         error(operation, u, fields, err)