Add support for making an idempotent POST. This allows retrying a POST that was interrupted. It involves creating a post once only (poe) url /rest/data/<class>/@poe/<random_token>. This url acts the same as a post to /rest/data/<class>. However once the @poe url is used, it can't be used for a second POST. To make these changes: 1) Take the body of post_collection into a new post_collection_inner function. Have post_collection call post_collection_inner. 2) Add a handler for POST to rest/data/class/@poe. This will return a unique POE url. By default the url expires after 30 minutes. The POE random token is only good for a specific user and is stored in the session db. 3) Add a handler for POST to rest/data/<class>/@poe/<random token>. The random token generated in 2 is validated for proper class (if token is not generic) and proper user and must not have expired. If everything is valid, call post_collection_inner to process the input and generate the new entry. To make recognition of 2 stable (so it's not confused with rest/data/<:class_name>/<:item_id>), removed @ from Routing::url_to_regex. The current Routing.execute method stops on the first regular expression to match the URL. Since item_id doesn't accept a POST, I was getting 405 bad method sometimes. My guess is the order of the regular expressions is not stable, so sometime I would get the right regexp for /data/<class>/@poe and sometime I would get the one for /data/<class>/<item_id>. By removing the @ from the url_to_regexp, there was no way for the item_id case to match @poe. There are alternate fixes we may need to look at. If a regexp matches but the method does not, return to the regexp matching loop in execute() looking for another match. Only once every possible match has failed should the code return a 405 method failure. Another fix is to implement a more sophisticated mechanism so that @Routing.route("/data/<:class_name>/<:item_id>/<:attr_name>", 'PATCH') has different regexps for matching <:class_name> <:item_id> and <:attr_name>. Currently the regexp specified by url_to_regex is used for every component. Other fixes: Made failure to find any props in props_from_args return an empty dict rather than throwing an unhandled error. Make __init__ for SimulateFieldStorageFromJson handle an empty json doc. Useful for POSTing to rest/data/class/@poe with an empty document. Testing: added testPostPOE to test/rest_common.py that I think covers all the code that was added. Documentation: Add doc to rest.txt in the "Client API" section titled: Safely Re-sending POST". Move existing section "Adding new rest endpoints" in "Client API" to a new second level section called "Programming the REST API". Also a minor change to the simple rest client moving the header setting to continuation lines rather than showing one long line.

#
# Copyright (C) 2009 Stefan Seefeld
# All rights reserved.
# For license terms see the file COPYING.txt.
# Actions used in REST and XMLRPC APIs
#

from roundup.exceptions import Unauthorised
from roundup import hyperdb
from roundup.i18n import _

class Action:
    def __init__(self, db, translator):
        self.db = db
        self.translator = translator

    def handle(self, *args):
        """Action handler procedure"""
        raise NotImplementedError

    def execute(self, *args):
        """Execute the action specified by this object."""

        self.permission(*args)
        return self.handle(*args)


    def permission(self, *args):
        """Check whether the user has permission to execute this action.

        If not, raise Unauthorised."""

        pass


    def gettext(self, msgid):
        """Return the localized translation of msgid"""
        return self.translator.gettext(msgid)


    _ = gettext


class PermCheck(Action):
    def permission(self, designator):

        classname, itemid = hyperdb.splitDesignator(designator)
        perm = self.db.security.hasPermission

        if not perm('Retire', self.db.getuid(), classname=classname
                   , itemid=itemid):
            raise Unauthorised(self._('You do not have permission to retire '
                                      'or restore the %(classname)s class.')
                                      %locals())

class Retire(PermCheck):

    def handle(self, designator):

        classname, itemid = hyperdb.splitDesignator(designator)

        # make sure we don't try to retire admin or anonymous
        if (classname == 'user' and
            self.db.user.get(itemid, 'username') in ('admin', 'anonymous')):
            raise ValueError(self._(
                'You may not retire the admin or anonymous user'))

        # do the retire
        self.db.getclass(classname).retire(itemid)
        self.db.commit()


class Restore(PermCheck):

    def handle(self, designator):

        classname, itemid = hyperdb.splitDesignator(designator)

        # do the restore
        self.db.getclass(classname).restore(itemid)
        self.db.commit()