Merge pull request #75 from deep-compute/error_codes

Error codes support

Author: pavan-maddula

.travis.yml

@@ -16,8 +16,8 @@ deploy:
     - LICENSE
     - kwikapi/api.py
     - kwikapi/__init__.py
-  name: kwikapi-0.4.9
-  tag_name: 0.4.9
+  name: kwikapi-0.5.0
+  tag_name: 0.5.0
   on:
     repo: deep-compute/kwikapi
 - provider: pypi

README.md

@@ -99,6 +99,7 @@ True
 - Bulk request handling
 - KwikAPI Client
 - Authentication
+- Custom error codes and messages
 
 ### Versioning support
 Versioning support will be used if user wants different versions of functionality with slightly changed behaviour.
@@ -643,7 +644,7 @@ api.register(Calc(), 'v1')
 def make_app():
     return tornado.web.Application([
         (r'^/api/.*', RequestHandler, dict(api=api)),
-    ])  
+    ])
 if __name__ == "__main__":
     app = make_app()
     app.listen(8818)
@@ -722,6 +723,95 @@ auth = b'Bearer %s' % b'key'
 headers['Authorization'] = auth
 ```
 
+### Custom error codes and messages
+KwikAPI supports error `codes` and `messages`.
+
+A global map of error messages and error codes are maintained across the KwikAPI. Every error code specifies a unique error message that is possible.
+
+**KwikAPI's default error code:**
+
+| Error | Code |
+| ---- | ---- |
+| Unknown / Internal Exception | 50000 |
+| Duplicate API function | 50001 |
+| Unknown API function | 50002 |
+| Protocol already exists | 50003 |
+| Unknown protocol | 50004 |
+| Unknown version | 50005 |
+| Unsupported type | 50006 |
+| Type not specified | 50007 |
+| Unknown version or namespace | 50008 |
+| Streaming not supported | 50009 |
+| Keyword argument error | 50010 |
+| Authentication error | 50011 |
+| Non-keyword arguments error | 50012 |
+
+Exceptions raised by API's return default error if not handled which is `50000` by default.
+
+#### Examples
+- Response with an error code and message:
+    > URL:`https://www.example.com/addd?a=10&b=20`
+
+    ```json
+     {
+       "message": "Unknown API Function: \"addd\"",
+       "code": 50002,
+       "error": "[(www.example.com) UnknownAPIFunction]",
+       "success": false
+     }
+    ```
+
+    To return custom error messages and code, developer must raise an exception object with attributes `message` and `code` in it.
+
+- Raising custom error message and error code
+    ```python
+    import tornado.web
+    import tornado.ioloop
+
+    from kwikapi import API
+    from kwikapi.tornado import RequestHandler
+
+    # custom exception
+    class CalcError(Exception):
+        def __init__(self, message="Input error", code=1101):
+            self.message = message
+            self.code = code
+
+    # Core logic that you want to expose as a service
+    class Calc(object):
+        def divide(self, a: int, b: int) -> int:
+            try:
+                return a / b
+            except:
+                raise CalcError(message="b can't be zero")
+
+    # Register BaseCalc with KwikAPI
+    api = API()
+    api.register(Calc(), 'v1')
+
+    # Passing RequestHandler to the KwikAPI
+    def make_app():
+        return tornado.web.Application([
+            (r'^/api/.*', RequestHandler, dict(api=api)),
+        ])
+
+    # Starting the application
+    if __name__ == "__main__":
+        app = make_app()
+        app.listen(8888)
+        tornado.ioloop.IOLoop.current().start()
+    ```
+    Response:
+    > URL:`https://www.example.com/divide?a=10&b=0`
+
+    ```json
+    {
+       "success": false,
+       "message": "b can't be zero",
+       "code": 1101,
+       "error": "[(www.example.com) CalcError]"
+    }
+    ```
 ## Run test cases
 ```bash
 $ python3 -m doctest -v README.md

kwikapi/api.py

@@ -20,6 +20,7 @@
 from .exception import DuplicateAPIFunction, UnknownAPIFunction
 from .exception import ProtocolAlreadyExists, UnknownProtocol
 from .exception import UnsupportedType, TypeNotSpecified
+from .exception import KeywordArgumentError
 
 from .utils import get_loggable_params
 
@@ -343,6 +344,7 @@ def get_api_fn(self, fn_name, version, namespace):
 class BaseRequestHandler(object):
     PROTOCOLS = PROTOCOLS
     DEFAULT_PROTOCOL = DEFAULT_PROTOCOL
+    DEFAULT_ERROR_CODE = 50000
 
     def __init__(self, api,
             default_version=None, default_protocol=DEFAULT_PROTOCOL,
@@ -455,8 +457,11 @@ def _find_request_protocol(self, request):
         return self.PROTOCOLS[protocol]
 
     def _handle_exception(self, req, e):
-        message = e.message if hasattr(e, 'message') else str(e)
-        message = '[(%s) %s: %s]' % (self.api._id, e.__class__.__name__, message)
+        message_value = e.message if hasattr(e, 'message') else str(e)
+        code_value = e.code if hasattr(e, 'code') else self.DEFAULT_ERROR_CODE
+        error_value = '[(%s) %s]' % (self.api._id, e.__class__.__name__)
+        success_value = False
+        message = dict(message=message_value, code=code_value, error=error_value, success=success_value)
 
         _log = req.log if hasattr(req, 'log') else self.log
         _log.exception('handle_request_error', message=message,
@@ -469,8 +474,7 @@ def _wrap_stream(self, req, res):
             for r in res:
                 yield dict(success=True, result=r)
         except Exception as e:
-            m = self._handle_exception(req, e)
-            yield dict(success=False, message=m)
+            yield self._handle_exception(req, e)
 
     def handle_request(self, request):
         if self.api._auth:
@@ -486,7 +490,14 @@ def handle_request(self, request):
 
             # invoke the API function
             tcompute = time.time()
-            result = request.fn(**request.fn_params)
+            try:
+                result = request.fn(**request.fn_params)
+            except TypeError as e:
+                if 'got an unexpected keyword argument' in str(e):
+                    raise KeywordArgumentError(e.args[0])
+                else:
+                    raise e
+
             tcompute = time.time() - tcompute
 
             response.headers[TIMING_HEADER] = str(tcompute)
@@ -509,7 +520,7 @@ def handle_request(self, request):
 
         except Exception as e:
             m = self._handle_exception(request, e)
-            response.write(dict(success=False, message=m), protocol)
+            response.write(m, protocol)
 
         response.flush()
         response.close()

kwikapi/auth.py

@@ -5,6 +5,7 @@
 from deeputil import xcode, AttrDict
 
 from .api import Request
+from .exception import AuthenticationError
 
 class BaseServerAuthenticator:
     '''Helps in authenticating a request on the server'''
@@ -16,7 +17,7 @@ def _read_auth(self, req):
         auth = req.headers.get('Authorization')
         _type, info = auth.split(' ', 1)
         if _type.lower() != self.TYPE:
-            raise Exception('Invalid auth type: %s' % _type) # FIXME: raise exc hierarchy
+            raise AuthenticationError(_type)
 
         auth = AuthInfo(type=self.TYPE)
         auth.header_info = info

kwikapi/client.py

@@ -6,7 +6,7 @@
 from deeputil import Dummy, ExpiringCache
 
 from .protocols import PROTOCOLS
-from .exception import APICallFailed
+from .exception import NonKeywordArgumentsError
 from .api import PROTOCOL_HEADER, REQUEST_ID_HEADER
 from .utils import get_loggable_params
 
@@ -47,7 +47,6 @@ class Client:
     def __init__(self, url, version=None, protocol=DEFAULT_PROTOCOL,
             path=None, request='', timeout=None, dnscache=None,
             headers=None, auth=None, stream=False, log=DUMMY_LOG):
-
         headers = headers or {}
 
         self._url = url
@@ -127,7 +126,8 @@ def _deserialize_response(data, protocol):
     def _extract_response(r):
         success = r['success']
         if not success:
-            raise Exception(r['message']) # FIXME: raise proper exc
+            r.pop('success')
+            raise Exception(r) # FIXME: raise proper exc
         else:
             r = r['result']
 
@@ -145,7 +145,8 @@ def _serialize_params(params, protocol):
         return data
 
     def __call__(self, *args, **kwargs):
-        assert(not args) # FIXME: raise appropriate exception
+        if args:
+            raise NonKeywordArgumentsError(args)
 
         if self._path:
             # FIXME: support streaming in both directions