slowlette 0.1.0__py3-none-any.whl

slowlette/__init__.py

@@ -0,0 +1,10 @@
+
+from .model import JSON, DictJSON
+from .request import Request
+from .response import Response, FileResponse
+from .router import Router, get, post, delete, route, on_event, websocket, eventstream
+from .websocket import WebSocket, WebSocketConnectionClosed
+from .eventstream import EventStream, EventStreamConnectionClosed
+from .middleware import BasicAuthentication, FileServer
+from .server import serve_asgi, serve_wsgi, serve_wsgi_ref, WSGI
+from .app import App, Slowlette

slowlette/app.py

@@ -0,0 +1,117 @@
+# Created by Sanshiro Enomoto on 19 January 2025 #
+
+import asyncio, inspect, logging
+
+from .router import Router, PathRule
+from .server import dispatch_asgi, dispatch_wsgi, serve_asgi, serve_wsgi
+
+
+class App:
+    """Slowlette App for ASGI
+    Note:
+      - User App can be derived from this class, or can be passed to the constructor parameter:
+        - Method 1: class MyApp(slowlette.App)  then  app = MyApp()
+        - Method 2: app = slowlette.App(MyApp())
+      - In either case,
+        - MyApp can use the Slowlette routing decorators.
+        - The app object implements ASGI.
+        - Sub-apps can be added by app.slowlette.include(MySubApp()).
+        - Middlewares can be added by app.slowlette.add_middleware(...)
+    """
+    
+    def __init__(self, subapp=None):
+        if not hasattr(self, 'slowlette'): # subclass might have defnied a custom router
+            self.slowlette = Router(self)
+            
+        if subapp is not None:
+            self.slowlette.include(subapp)
+            
+            
+    async def __call__(self, scope, receive, send):
+        """ASGI entry point
+        """
+        if not hasattr(self, 'slowlette'): # __init__() might not have been called
+            self.slowlette = Router(self)
+
+        await dispatch_asgi(self, scope, receive, send)
+    
+
+    def run(self, port=8000, **kwargs):
+        """Run HTTP Server
+        """
+        serve_asgi(self, port, **kwargs)
+
+
+
+class Slowlette(App):
+    """Slowlette App that can assign URL endpoints to functions, instead of class methods
+    """
+    
+    class FunctionAdapter:
+        def __init__(self, func):
+            self.func = func
+        async def __call__(self, app, *args, **kwargs):
+            result = self.func(*args, **kwargs)
+            if inspect.isawaitable(result):
+                return await result
+            else:
+                return result
+
+    def __init__(self):
+        super().__init__()
+
+
+    def get(self, path_rule:str, status_code:int=200):
+        """decorator to make a GET-request handler (Python function)
+        Args:
+            - path_rule: path pattern to match
+            - status_code: default status code for success
+        """
+        def wrapper(func):
+            adapter = self.FunctionAdapter(func)
+            adapter.slowlette_path_rule = PathRule(path_rule, 'GET', func, status_code=status_code)
+            self.slowlette.handlers.append(adapter)
+            return func
+        return wrapper
+
+    
+    def post(self, path_rule:str, status_code:int=201):
+        """decorator to make a POST-request handler (Python function)
+        Args:
+            - path_rule: path pattern to match
+            - status_code: default status code for success
+        """
+        def wrapper(func):
+            adapter = self.FunctionAdapter(func)
+            adapter.slowlette_path_rule = PathRule(path_rule, 'POST', func, status_code=status_code)
+            self.slowlette.handlers.append(adapter)
+            return func
+        return wrapper
+
+    
+    def delete(self, path_rule:str, status_code:int=200):
+        """decorator to make a DELETE-request handler (Python function)
+        Args:
+            - path_rule: path pattern to match
+            - status_code: default status code for success
+        """
+        def wrapper(func):
+            adapter = self.FunctionAdapter(func)
+            adapter.slowlette_path_rule = PathRule(path_rule, 'DELETE', func, status_code=status_code)
+            self.slowlette.handlers.append(adapter)
+            return func
+        return wrapper
+
+    
+    def route(self, path_rule:str, status_code:int=200):
+        """decorator to make a request handler (Python function) for all request methods
+        Args:
+            - path_rule: path pattern to match
+            - status_code: default status code for success
+        """
+        def wrapper(func):
+            adapter = self.FunctionAdapter(func)
+            adapter.slowlette_path_rule = PathRule(path_rule, '*', func, status_code=status_code)
+            self.slowlette.handlers.append(adapter)
+            return func
+        return wrapper

slowlette/eventstream.py

@@ -0,0 +1,91 @@
+# Created by Sanshiro Enomoto on 9 July 2026 #
+
+import json
+
+
+class EventStream:
+    def __init__(self, receive_func, send_func):
+        self.receive_func = receive_func
+        self.send_func = send_func
+        self.is_accepted = False
+        self.is_closed = False
+
+
+    async def accept(self):
+        if self.is_accepted:
+            return
+        await self.send_func({
+            'type': 'http.response.start',
+            'status': 200,
+            'headers': [
+                (b'content-type', b'text/event-stream; charset=utf-8'),
+                (b'cache-control', b'no-cache'),
+                (b'x-accel-buffering', b'no'),
+            ],
+        })
+        self.is_accepted = True
+
+
+    async def close(self, code=1000):
+        if self.is_closed:
+            return
+        await self.accept()
+        await self.send_func({
+            'type': 'http.response.body',
+            'body': b'',
+            'more_body': False,
+        })
+        self.is_closed = True
+
+        
+    async def send(self, data, *, event=None, id=None, retry=None):
+        await self.accept()
+
+        lines = []
+        if id is not None:
+            lines.append(f'id: {id}')
+        if event is not None:
+            lines.append(f'event: {event}')
+        if retry is not None:
+            lines.append(f'retry: {retry}')
+
+        if type(data) is bytes:
+            text = data.decode()
+        elif type(data) is str:
+            text = data
+        else:
+            text = json.dumps(data)
+
+        for line in text.splitlines() or ['']:
+            lines.append(f'data: {line}')
+
+        payload = ('\n'.join(lines) + '\n\n').encode()
+    
+        await self.send_func({
+            'type': 'http.response.body',
+            'body': payload,
+            'more_body': True,
+        })
+
+
+    async def comment(self, text=''):
+        await self.accept()
+        lines = str(text).splitlines() or ['']
+        body = ''.join(f': {line}\n' for line in lines) + '\n'
+        await self.send_func({
+            'type': 'http.response.body',
+            'body': body.encode(),
+            'more_body': True,
+        })
+
+
+    async def wait_disconnected(self):
+        while True:
+            message = await self.receive_func()
+            if message['type'] == 'http.disconnect':
+                raise EventStreamConnectionClosed()
+
+
+
+class EventStreamConnectionClosed(Exception):
+    pass

slowlette/middleware.py

@@ -0,0 +1,197 @@
+# Created by Sanshiro Enomoto on 18 January 2025 #
+
+
+import sys, os, base64, logging
+
+from .request import Request
+from .response import Response, FileResponse
+from .router import route
+
+
+class BasicAuthentication():
+    def __init__(self, realm='Slowlette', auth_list=[]):
+        self.realm = realm
+
+        self.auth_list = {}
+        for auth in auth_list:
+            try:
+                (user, key) = tuple(auth.split(':', 1))
+            except:
+                # auth is already encrypted
+                logging.error('Bad authentication entry: %s' % auth)
+                continue
+            self.auth_list[user] = key
+        
+        if len(self.auth_list) > 0:
+            try:
+                global bcrypt
+                import bcrypt
+            except:
+                logging.critical('Slowlette_BasicAuthentication: missing python module "bcrypt"')
+                sys.exit(-1)
+        
+
+    def require_auth(self, request:Request) -> Response:
+        request.abort()
+        response = Response(401)   # Unauthorized
+        response.headers['WWW-Authenticate'] = f'Basic realm="{self.realm}"'
+        return response
+    
+        
+    @route('/{*}')
+    def dispatch(self, request:Request, body:bytes=None) -> Response:
+        if len(self.auth_list) == 0:
+            return Response()
+
+        auth = request.headers.get('authorization', request.headers.get('Authorization', None))
+        if auth == '' or auth is None:
+            return self.require_auth(request)
+
+        try:
+            user, word = tuple(base64.b64decode(auth.split(' ')[1]).decode().split(':'))
+            true_key = self.auth_list.get(user, None)
+            if word is None or true_key is None:
+                return self.require_auth(request)
+
+            # key is hashed and this is safe against timing attack; but this is very slow...
+            key = bcrypt.hashpw(word.encode("utf-8"), true_key.encode()).decode("utf-8")
+            if key == true_key:    
+                request.user = user
+                return Response()
+                
+        except Exception as e:
+            logging.warning(f'Slowlette_BasicAuthentication: Authentication Error: {str(e)}')
+            
+        return self.require_auth(request)
+
+
+    @staticmethod
+    def generate_key(username:str, password:str) -> str:
+        import bcrypt
+        return username + ':' + bcrypt.hashpw(password.encode(), bcrypt.gensalt(rounds=12, prefix=b"2a")).decode()
+        
+
+
+class FileServer():
+    def __init__(self, filedir, *, prefix="", index_file=None, exclude=None, not_found_is_error=True, ext_allow=None, ext_deny=None):
+        """File Server App (Middleware)
+        Args:
+          - filedir (str): path to a filesystem directory
+          - prefix (str): URL path to bind this app (e.g., "/webfile")
+          - index_file (str): index file when the path is empty (i.e., '/')
+          - exclude (str or list[str]): URL path(s) not to be handled
+            (e.g., prefix="/app" and exclude="/api" to exclude "/app/api")
+          - not_found_is_error (bool): if true return an error response (404) if file does not exist, otherwise propagate
+          - ext_allow (list[str]): a list of file extensions to allow accessing
+          - ext_deny (list[str]): a list of file extensions not to allow accessing
+        Note:
+          - file/dir names are restricted to:
+            - start with an alphabet or digit
+            - consist of only alphabets, digits, and selected special characters (_, -, +, ., =, ',', ':')
+        """
+
+        self.filedir = filedir
+        self.prefix = None
+        self.index_file = index_file
+        self.exclude = None
+        self.not_found_is_error = not_found_is_error
+        self.ext_allow = ext_allow
+        self.ext_deny = ext_deny
+
+        if prefix is not None:
+            self.prefix = [ p for p in prefix.split('/') if len(p) > 0 ]
+        if exclude is None:
+            self.excludes = []
+        else:
+            self.excludes = [
+                [ p for p in entry.split('/') if len(p) > 0 ]
+                for entry in (exclude if type(exclude) is list else [ exclude ])
+            ]
+
+
+    @route('/{*}')
+    async def dispatch(self, request:Request, body:bytes=None) -> Response:
+        # sanity check
+        path = []
+        is_dirty = False
+        for p in request.path:
+            if len(p) == 0:
+                continue
+            if not p[0].isalnum():
+                is_dirty = True
+            if not p.replace('_','').replace('-','').replace('+','').replace('=','').replace('.','').replace(',','').replace(':','').isalnum():
+                is_dirty = True
+            path.append(p)
+
+        # prefix match
+        if self.prefix is not None:
+            if len(path) < len(self.prefix):
+                # no match -> propagate
+                return Response()
+            else:
+                for i,p in enumerate(self.prefix):
+                    if path[i] != p:
+                        # no match -> propagate
+                        return Response()
+            path = path[len(self.prefix):]
+            
+        # exclude-path match
+        for exclude in self.excludes:
+            if len(path) >= len(exclude):
+                for i,p in enumerate(exclude):
+                    if path[i] != p:
+                        break
+                else:
+                    # match to exclusion
+                    return Response()
+                
+        # method match
+        # We apply URL rewriting even for non-GET methods (like POST api/command -> /command),
+        # so this method check must be after the exclusion match.
+        if request.method != 'GET':
+            return Response()  # propagate
+        
+        # matched -> my responsibility (can return an error status) #
+
+        if self.not_found_is_error:
+            request.abort()            
+            
+        if is_dirty:
+            logging.warning(f'Slowlette File GET: Forbidden: sanity check failed')
+            return Response(403)  # Forbidden
+        if len(path) == 0:
+            if self.index_file is not None:
+                path = [ self.index_file ]
+            else:
+                logging.warning(f'Slowlette File GET: Forbidden: no directory indexing')
+                return Response(403)  # Forbidden
+        
+        # file extension check
+        ext = os.path.splitext(path[-1])[1]
+        if self.ext_allow is not None:
+            if ext not in self.ext_allow:
+                logging.warning(f'Slowlette File GET: Forbidden: file type not allowed')
+                return Response(403)  # Forbidden
+        elif self.ext_deny is not None:
+            if ext in self.ext_deny:
+                logging.warning(f'Slowlette File GET: Forbidden: file type denied')
+                return Response(403)  # Forbidden
+
+        filepath = os.path.join(*(path))
+        if len(os.path.splitdrive(filepath)[0]) > 0:  # Windows drive letter :-(
+            logging.warning(f'Slowlette File GET: Forbidden: includes Windows drive letter')
+            return Response(403)  # Forbidden
+                
+        filepath = os.path.join(self.filedir, filepath)
+
+        if not os.path.isfile(filepath):
+            logging.warning(f'Slowlette File GET: file not found: {filepath} in {self.filedir}')
+            if self.not_found_is_error:
+                return Response(404)  # Not found
+            else:
+                return Response()  # propagate
+        
+        logging.debug(f'Slowlette_FileServer: file request: {filepath}')
+
+        return await FileResponse().load(filepath)
+

slowlette/model.py

@@ -0,0 +1,107 @@
+# Created by Sanshiro Enomoto on 10 January 2025 #
+
+
+import json, logging
+
+
+class JSON:
+    """Custom type for Slowlette to recognize that the request-body is a JSON string
+    Note:
+      - If a request-handler parameter is of this type, Slowlette interprets the body as JSON.
+        - Example:
+          | @Slowlette.post('/doc')
+          | def process_doc(doc: JSON):
+          |   param1 = doc.get('param1', 0)
+      - If the parsing fails, it returns response 400 (Bad Request) and the handler will not be called.
+      - If the content data is a dict or list, JSON object can be used as dict or list for common methods,
+      - Or use the "value()" method to get the native Python type object.
+    """
+    
+    def __init__(self, body):
+        try:
+            if type(body) is bytes:
+                self.data = json.loads(body.decode())
+            else:
+                self.data = body
+        except Exception as e:
+            logging.error('Slowlette: JSON decoding error: %s' % str(e))
+            self.data = None
+
+            
+    def value(self):
+        return self.data
+            
+
+    def __iter__(self):
+        if type(self.data) is dict:
+            for k, v in self.data.items():
+                yield k, v
+        elif type(self.data) is list:
+            for v in self.data:
+                yield v
+
+                
+    def __str__(self):
+        return str(self.data)
+
+    def __repr__(self):
+        return repr(self.data)
+
+    def __len__(self):
+        return len(self.data)
+
+    def __getitem__(self, index):
+        return self.data[index]
+
+    def __setitem__(self, index, value):
+        self.data[index] = value
+
+    def __delitem__(self, index):
+        del self.data[index]
+
+    def __contains__(self, item):
+        return item in self.data
+
+    def get(self, key, default_value=None):
+        # no type check on purpose: letting the error messages (and stack trace) displayed
+        return self.data.get(key, default_value)
+    
+    def keys(self):
+        # no type check on purpose
+        return self.data.keys()
+
+    def values(self):
+        # no type check on purpose
+        return self.data.values()
+
+    def items(self):
+        # no type check on purpose
+        return self.data.items()
+
+
+
+class DictJSON(dict):
+    """same as JSON, but the content must be a valid dict, and the instance is a dict
+    """
+    def __init__(self, body):
+        try:
+            if type(body) is bytes:
+                data = json.loads(body.decode())
+            else:
+                data = body
+        except Exception as e:
+            logging.error(f'Slowlette: JSON decoding error: {e}: {body}')
+            self._is_valid = False
+            return
+
+        if type(data) is not dict:
+            logging.error(f'Slowlette: DictJSON content is not a dict: {e}')
+            self._is_valid = False
+            return
+            
+        super().__init__(data)
+        self._is_valid = True
+
+            
+    def value(self):
+        return dict(self) if self._is_valid else None

slowlette/request.py

@@ -0,0 +1,32 @@
+# Created by Sanshiro Enomoto on 11 January 2025 #
+
+import copy, logging
+from urllib.parse import urlparse, parse_qsl, unquote
+
+
+class Request:
+    is_async = True  # True for ASGI; WSGI will change this directly
+    
+    def __init__(self, url, method="GET", *, headers={}, body=None):
+        self.method = method.upper()
+        self.headers = copy.deepcopy(headers)
+        self.body = body
+        
+        self.aborted = False
+
+        u = urlparse(url)
+        self.path_str = u.path
+        self.query_str = u.query
+        
+        self.path = [ unquote(p) for p in self.path_str.split('/') ]
+        self.query = { unquote(key): unquote(value) for key, value in parse_qsl(self.query_str) }
+        while self.path.count(''):
+            self.path.remove('')
+
+
+    def abort(self):
+        self.aborted = True
+
+
+    def __str__(self):
+        return f"{self.method} /{'/'.join(self.path)}{'?' if len(self.query)>0 else ''}{'&'.join(['%s=%s'%(k,v) for k,v in self.query.items()])}"