lapis-api 0.2.0__py3-none-any.whl

lapis/__init__.py

@@ -0,0 +1,10 @@
+"""Lapis web framework core exports.
+
+This module exposes the primary public classes for consumers of the
+lapis package.
+"""
+
+from .lapis import Lapis
+from .server_types import ServerConfig, Protocol
+from .protocols.http1 import Request, Response, StreamedResponse
+from .protocols.websocket import WebSocketProtocol, WSPortal

lapis/lapis.py

@@ -0,0 +1,273 @@
+"""
+The main script for the Lapis server handling initial request handling and response
+"""
+
+import asyncio
+import inspect
+import select
+import socket
+import pathlib
+import runpy
+import sys
+from threading import Thread
+from datetime import datetime
+
+from lapis.protocols.websocket import WebSocketProtocol
+from lapis.protocols.http1 import HTTP1Protocol, Request, Response
+from .server_types import (
+    BadAPIDirectory,
+    BadConfigError,
+    BadRequest,
+    Protocol,
+    ServerConfig,
+    ProtocolEndpointError
+)
+
+class Lapis:
+    """
+    The Lapis class implements the centeral object used to run a Lapis REST server
+    """
+    cfg: ServerConfig = ServerConfig()
+
+    __s: socket.socket = None
+    __paths: dict = {}
+    __taken_endpoints : list[str] = []
+    __protocols : list[type[Protocol]] = []
+
+    __running : bool = False
+
+    def __init__(self, config: ServerConfig | None = None):
+
+        if config is not None:
+            self.cfg = config
+
+        self.__register_protocol(HTTP1Protocol)
+        self.__register_protocol(WebSocketProtocol)
+
+        self.__paths = self._bake_paths()
+
+    def run(self, ip: str, port: int):
+        """
+        Starts the Lapis server to listen on a given ip and port
+        
+        :param ip: The ip for the server to listen on
+        :type ip: str
+        :param port: The port for the server to listen on
+        :type port: int
+        """
+        self.__s = socket.socket()
+        self.__s.bind((ip, port))
+        self.__s.listen()
+
+        self.__running = True
+        print(f"{self.cfg.server_name} is now listening on http://{ip}:{port}")
+
+        try:
+            while True:
+                readable, _, _ = select.select([self.__s], [], [], 0.1)
+                if self.__s in readable:
+                    client, _ = self.__s.accept()
+                    t = Thread(target=self._handle_request, args=(client,), daemon=True)
+                    t.start()
+        except KeyboardInterrupt:
+            pass
+        finally:
+            self.__close()
+
+    def __register_protocol(self, protocol : type[Protocol]):
+
+        if self.__running:
+            raise RuntimeError("Cannot register new Protocol while server is running")
+
+        endpoints : list[str] = protocol().get_target_endpoints()
+        if bool(set(endpoints) & set(self.__taken_endpoints)):
+            raise ProtocolEndpointError("Cannot reuse target endpoint method!")
+
+        self.__protocols.insert(0, protocol)
+        self.__taken_endpoints.extend(endpoints)
+
+    def register_protocol(self, protocol : type[Protocol]):
+        """
+        Registers new protocol for the server to use to communicate with clients
+
+        Cannot be called while server is running
+
+        :param protocol: Description
+        :type protocol: type[Protocol]
+        """
+        self.__register_protocol(protocol=protocol)
+
+        self.__paths = self._bake_paths()
+
+    def _get_dynamic_dirs(self, directory: pathlib.Path):
+        return [
+            p for p in directory.iterdir()
+            if p.is_dir() and p.name.startswith("[") and p.name.endswith("]")
+        ]
+
+    def _bake_paths(self) -> dict:
+
+        server_path = pathlib.Path(sys.argv[0]).resolve()
+        root : pathlib.Path = server_path.parent / pathlib.Path(self.cfg.api_directory)
+
+        try:
+            root.parent.resolve(strict=False)
+        except (OSError, RuntimeError) as err:
+            raise BadConfigError("\"api_directory\" in config must be a valid file path") from err
+
+        if not root.exists():
+            raise BadAPIDirectory(f"api directory \"{root}\" does not exist")
+
+        result = {}
+
+        for path in root.rglob(f"{self.cfg.path_script_name}.py"):
+            if not path.is_file():
+                continue
+
+            parts = path.relative_to(root).parts
+            current_level = result
+            current_fs_level = root
+
+            for part in parts[:-1]:
+                dynamic_dirs = self._get_dynamic_dirs(current_fs_level)
+                if len(dynamic_dirs) > 1:
+                    raise BadAPIDirectory(
+                        f"Multiple dynamic route folders in {current_fs_level}: "
+                        f"{', '.join(d.name for d in dynamic_dirs)}"
+                    )
+
+                # move filesystem pointer
+                current_fs_level = current_fs_level / part
+
+                current_level = current_level.setdefault(part, {})
+
+            script_globals = runpy.run_path(str(path.absolute()))
+
+            # Grab just endpoint methods
+            api_routes = {
+                f"/{k}": v
+                for k, v in script_globals.items()
+                if k in self.__taken_endpoints
+            }
+
+            # Add endpoints
+            current_level.update(api_routes)
+        return result
+
+    def __has_endpoint_path(self, base_url : str) -> tuple[dict[str, any] | None, dict[str,str]]:
+        # Digs through api cache map to find the correct endpoint directory
+        slugs = {}
+        path = pathlib.Path(f"{self.cfg.api_directory}{base_url}")
+        parts : list[str] = path.relative_to(self.cfg.api_directory).parts
+
+        leaf : dict = self.__paths
+        for part in parts:
+            if part in leaf:
+                leaf = leaf[part]
+                continue
+
+            # checks if there are dynamic routes available
+            dynamic_routes: list[str] = list(
+                {
+                    key
+                    for key in leaf
+                    if key.startswith("[") and key.endswith("]")
+                }
+            )
+
+            if len(dynamic_routes) == 1:
+                slugs[dynamic_routes[0].strip("[]")] = part
+                leaf = leaf[dynamic_routes[0]]
+            else:
+                return (None, {})
+
+        if len(leaf) == 0:
+            return (None, {})
+
+        return (leaf, slugs)
+
+    def _handle_request(self, client: socket.socket):
+        data = client.recv(self.cfg.max_request_size)
+
+        try:
+            request : Request = Request(data)
+
+        except BadRequest:
+            self.__send_response(client, Response(status_code=400, body="400 Bad Request"))
+            client.close()
+            return
+
+        try:
+            (endpoint, request.slugs) = self.__has_endpoint_path(request.base_url)
+
+            if endpoint is None:
+                raise FileNotFoundError()
+
+            # Finds the correct protocol based on the inital request
+            for protocol_cls in self.__protocols:
+                protocol: Protocol = protocol_cls()
+
+                if not protocol.identify(initial_data=data):
+                    continue
+
+                if not protocol.handshake(client=client):
+                    raise BadRequest("Failed Handshake with protocol!")
+
+                target_endpoints = protocol.get_target_endpoints()
+
+                endpoints = {
+                    f"/{k}": endpoint[f"/{k}"]
+                    for k in target_endpoints
+                    if f"/{k}" in endpoint
+                }
+
+                endpoints = { key.lstrip("/"): value for key, value in endpoints.items() }
+
+                if inspect.iscoroutinefunction(protocol.handle):
+                    asyncio.run(protocol.handle(
+                        client=client,
+                        slugs=request.slugs,
+                        endpoints=endpoints,
+                    ))
+                else:
+                    protocol.handle(
+                        client=client,
+                        slugs=request.slugs,
+                        endpoints=endpoints,
+                    )
+
+                break
+            else: # No Protocol was found to be compatible
+                raise BadRequest("No Compatible Protocol Found!")
+
+
+        except BadRequest:
+            response : Response = Response(status_code=400, body="400 Bad Request")
+            self.__send_response(client=client, response=response)
+
+        except FileNotFoundError:
+            response : Response = Response(status_code=404, body="404 Not Found")
+            self.__send_response(client, response)
+
+        except RuntimeError as e:
+            print(f"Error handling request: {e}")
+            response = Response(status_code=500, body="Internal Server Error")
+            self.__send_response(client, response)
+
+        finally:
+            client.close()
+
+    def __send_response(self, client : socket.socket, response : Response):
+        client.sendall(response.to_bytes())
+        current_time = datetime.now().strftime("%H:%M:%S")
+        ip, _ = client.getpeername()
+        print(f"{current_time} {response.status_code.value} -> {ip}")
+
+    def __close(self):
+        if self.__s is not None:
+            try:
+                print("Closing Server...")
+                self.__running = False
+                self.__s.close()
+            except socket.error as e:
+                print(f"Error when closing socket: {e}")

lapis/protocols/http1.py

@@ -0,0 +1,251 @@
+"""
+Module containing the HTTP 1/1.1 protocol implementation for Lapis server
+"""
+
+from dataclasses import dataclass
+from datetime import datetime
+from http import HTTPMethod, HTTPStatus
+import socket
+from typing import AsyncGenerator, Callable
+from urllib.parse import parse_qsl, urlparse
+
+from lapis.server_types import BadRequest, Protocol
+
+@dataclass
+class RequestHeader:
+    """
+    Utility class to store the request header data
+    """
+    method: HTTPMethod
+    base_url: str
+    query_params: dict[str, str]
+    headers: dict[str, str]
+    protocol: str
+
+class Request:
+    """
+    The object class for handling HTTP 1/1.1 requests from clients
+    """
+
+    def __init__(self, data: bytes):
+        try:
+            text = data.decode("iso-8859-1")
+        except UnicodeDecodeError as err:
+            raise BadRequest("Invalid encoding") from err
+
+        if "\r\n\r\n" not in text:
+            raise BadRequest("Malformed HTTP request")
+
+        head, self.__body = text.split("\r\n\r\n", 1)
+        lines = head.split("\r\n")
+
+        method_str, url, protocol = lines[0].split(" ", 2)
+        if protocol not in ("HTTP/1.0", "HTTP/1.1"):
+            raise BadRequest("Unsupported protocol")
+
+        headers_dict = {}
+        for line in lines[1:]:
+            if ":" not in line:
+                raise BadRequest("Malformed header")
+            key, value = line.split(":", 1)
+            headers_dict[key.strip()] = value.strip()
+
+        if protocol == "HTTP/1.1" and "Host" not in headers_dict:
+            raise BadRequest("Missing Host header")
+
+        try:
+            parsed = urlparse(url)
+        except ValueError as exc:
+            raise BadRequest("Bad URL") from exc
+
+        self.__header_data = RequestHeader(
+            method=HTTPMethod[method_str.upper()],
+            base_url=parsed.path,
+            query_params=dict(parse_qsl(parsed.query)),
+            headers=headers_dict,
+            protocol=protocol
+        )
+
+        self.cookies = {}
+        self.slugs = {}
+
+    @property
+    def method(self) -> HTTPMethod:
+        """
+        Returns the HTTP method (e.g., GET, POST) of the request.
+        """
+        return self.__header_data.method
+
+    @property
+    def protocol(self) -> str:
+        """
+        Returns the HTTP protocol version (e.g., 'HTTP/1.1').
+        """
+        return self.__header_data.protocol
+
+    @property
+    def headers(self) -> dict[str, str]:
+        """
+        Returns a dictionary of the HTTP headers sent by the client.
+        Keys are case-sensitive as parsed from the request.
+        """
+        return self.__header_data.headers
+
+    @property
+    def base_url(self) -> str:
+        """
+        Returns the path component of the requested URL (e.g., '/api/users').
+        """
+        return self.__header_data.base_url
+
+    @property
+    def query_params(self) -> dict[str, str]:
+        """
+        Returns a dictionary containing the URL query string parameters.
+        """
+        return self.__header_data.query_params
+
+    @property
+    def body(self) -> str:
+        """
+        Returns the raw entity body of the HTTP request as a string.
+        """
+        return self.__body
+
+
+class Response:
+
+    """
+    The object class for forming a HTTP 1/1.1 response to the client from the server
+    """
+
+    def __init__(self,
+                 status_code : int | HTTPStatus = HTTPStatus.OK,
+                 body : str = "",
+                 headers : dict[str, any] = None,
+                 ):
+        self.status_code = (status_code
+                            if isinstance(status_code, HTTPStatus)
+                            else HTTPStatus(status_code))
+
+        self.protocol = "HTTP/1.1"
+        self.headers = headers if headers is not None else {
+            "Content-Type": "text/plain",
+        }
+        self.cookies = {}
+        self.body = body
+
+    @property
+    def reason_phrase(self):
+        """
+        Returns the reasoning behind the status code
+        """
+        return self.status_code.phrase
+
+    def to_bytes(self):
+        """
+        Returns the raw byte format of the Response class
+        """
+        body_bytes = self.body.encode('utf-8')
+        if "Content-Length" not in self.headers:
+            self.headers["Content-Length"] = len(body_bytes)
+
+        response_line = f"{self.protocol} {self.status_code.value} {self.reason_phrase}\r\n"
+        headers = "".join(f"{k}: {v}\r\n" for k, v in self.headers.items())
+        cookies = "".join(f"Set-Cookie: {k}={v}\r\n" for k, v in self.cookies.items())
+
+        return (response_line + headers + cookies + "\r\n").encode('utf-8') + body_bytes
+
+class StreamedResponse(Response):
+
+    """
+    A variant of the Response class that allows the server to stream back a response to the client
+    """
+
+    def __init__(
+            self,
+            stream : Callable[[Request], AsyncGenerator[bytes, None]],
+            status_code = HTTPStatus.OK,
+            headers : dict[str, str] = None):
+
+        super().__init__(status_code, "", headers)
+
+        self.stream = stream
+
+        self.headers["Transfer-Encoding"] = "chunked"
+
+    def get_head(self) -> bytes:
+        """
+        :return: The inital head of the streamed response from the server
+        :rtype: bytes
+        """
+        response_line = f"{self.protocol} {self.status_code.value} {self.reason_phrase}\r\n"
+        headers = "".join(f"{k}: {v}\r\n" for k, v in self.headers.items())
+        cookies = "".join(f"Set-Cookie: {k}={v}\r\n" for k, v in self.cookies.items())
+
+        return (response_line + headers + cookies + "\r\n").encode('utf-8')
+
+class HTTP1Protocol(Protocol):
+
+    """
+    The protocol created to handle HTTP 1/1.1 communications between server and client
+    """
+
+    request : Request = None
+
+    def get_config_key(self):
+        return "http1.x_config"
+
+    def get_target_endpoints(self) -> list[str]:
+        return [method.name for method in HTTPMethod]
+
+    def identify(self, initial_data):
+        try:
+            self.request = Request(initial_data)
+            return True
+        except BadRequest:
+            return False
+
+    def handshake(self, client : socket.socket):
+        # don't know how this would create an exception but its here just to be safe
+
+        current_time = datetime.now().strftime("%H:%M:%S")
+        ip, _ = client.getpeername()
+        print(f"{current_time} {self.request.method} {self.request.base_url} {ip}")
+        return True
+
+    async def handle(self, client : socket.socket, slugs, endpoints):
+
+        self.request.slugs = slugs
+
+        if self.request.method in endpoints:
+            response : Response = await endpoints[self.request.method](self.request)
+
+            ip, _ = client.getpeername()
+
+            if isinstance(response, StreamedResponse):
+                client.sendall(response.get_head())
+
+                current_time = datetime.now().strftime("%H:%M:%S")
+
+                print(f"{current_time} {response.status_code.value} STREAM -> {ip}")
+
+                async for packet in response.stream(self.request):
+                    chunk_len = f"{len(packet):X}\r\n".encode('utf-8')
+                    client.sendall(chunk_len + packet + b"\r\n")
+
+                    current_time = datetime.now().strftime("%H:%M:%S")
+
+                client.sendall(b"0\r\n\r\n")
+
+                print(f"{current_time} {response.status_code.value} STREAM FINISHED -> {ip}")
+
+
+            else:
+                client.sendall(response.to_bytes())
+
+                current_time = datetime.now().strftime("%H:%M:%S")
+
+                print(f"{current_time} {response.status_code.value} -> {ip}")
+        else:
+            raise FileNotFoundError()

lapis/protocols/websocket.py

@@ -0,0 +1,544 @@
+"""
+The Module containing Lapis' native WebSocket Protocol Handler
+"""
+
+import asyncio
+import binascii
+from datetime import datetime
+import socket
+import base64
+import hashlib
+from enum import Enum
+
+from lapis.server_types import Protocol
+from lapis.protocols.http1 import Request, Response
+
+class WSRecvTimeoutError(Exception):
+    """
+    The Exception raised when recieve request times out
+    """
+
+class WSRecvInvalidFrameError(Exception):
+    """
+    The Exception raised when the recieved frame is invalid
+    """
+
+class WSPortalClosedError(Exception):
+    """
+    The Exception raised when trying to recieve/send from a closed portal
+    """
+
+class WSOpcode(Enum):
+    """
+    The class containing all opcodes for a WSFrame to contain
+    """
+    CONTINUATION = 0x0
+    TEXT         = 0x1
+    BINARY       = 0x2
+    CLOSE        = 0x8
+    PING         = 0x9
+    PONG         = 0xA
+
+class WSFrame():
+    """
+    The class used to handle frame data between server and client
+    """
+    __data: bytes
+
+    def __init__(self, data: bytes):
+        if len(data) < 2:
+            raise ValueError("Data too short to be a WebSocket frame")
+
+        self.__data = data
+
+    @property
+    def fin(self) -> bool:
+        """
+        Returns if this frame is the final frame of the payload
+
+        Used for fragmented data frames
+        
+        :rtype: bool
+        """
+
+        return bool(self.__data[0] & 0x80)
+
+    @property
+    def opcode(self) -> WSOpcode:
+        """
+        Returns the frame's opcode; the operation the frame is supposed to communicate
+
+        :rtype: WSOpcode
+        """
+
+        return WSOpcode(self.__data[0] & 0x0F)
+
+    @property
+    def masked(self) -> bool:
+        """
+        Returns of the payload of the frame is masked
+        
+        :rtype: bool
+        """
+
+        return bool(self.__data[1] & 0x80)
+
+    @property
+    def payload_length(self) -> int:
+        """
+        Returns the length of the payload specified in the frame header
+                
+        :rtype: int
+        """
+
+        length = self.__data[1] & 0x7F
+
+        if length < 126:
+            return length
+        if length == 126:
+            return int.from_bytes(self.__data[2:4], "big")
+        return int.from_bytes(self.__data[2:10], "big")
+
+    def __header_length(self) -> int:
+        """
+        Returns the length of the header of the frame
+        
+        :rtype: int
+        """
+
+        length = self.__data[1] & 0x7F
+
+        if length < 126:
+            return 2
+        if length == 126:
+            return 4
+        return 10
+
+    @property
+    def masking_key(self) -> bytes | None:
+        """
+        Returns the masking key of the frame used to mask the payload
+
+        returns None if the frame isn't masked
+
+        :rtype: bytes | None
+        """
+
+        if not self.masked:
+            return None
+
+        start = self.__header_length()
+        return self.__data[start:start + 4]
+
+    @property
+    def data(self) -> str | bytes:
+        """
+        Returns the payload data of the frame
+
+        returns either string or bytes depending on the opcode
+        
+        :rtype: str | bytes
+        """
+        header_len = self.__header_length()
+        offset = header_len + (4 if self.masked else 0)
+
+        payload = self.__data[offset:offset + self.payload_length]
+
+        # Unmask if needed
+        if self.masked:
+            payload = bytes(b ^ self.masking_key[i % 4] for i, b in enumerate(payload))
+
+        # Decode based on opcode
+        if self.opcode == WSOpcode.TEXT:
+            try:
+                return payload.decode("utf-8")
+            except UnicodeDecodeError as e:
+                raise ValueError("Invalid UTF-8 in TEXT frame") from e
+
+        return payload
+
+    def __str__(self) -> str:
+        """
+        Returns a stringified version of WSFrame for debugging purposes
+        
+        :rtype: str
+        """
+
+        payload_preview = self.data
+        # Truncate if payload is too long for readability
+        if isinstance(payload_preview, bytes):
+            payload_preview = payload_preview[:50]
+            payload_preview = payload_preview.hex() + ("..." if len(self.data) > 50 else "")
+        elif isinstance(payload_preview, str):
+            payload_preview = payload_preview[:50] + ("..." if len(self.data) > 50 else "")
+
+        return (
+            f"WSFrame(fin={self.fin}, opcode={self.opcode}, masked={self.masked}, "
+            f"payload_length={self.payload_length}, payload={payload_preview})"
+        )
+
+class WSPortal():
+    """
+    The interface the Websocket endpoint function uses to communicate between server and client
+    """
+    slugs : dict[str, str] = {}
+
+    def __init__(self, slugs, client : socket.socket):
+
+        self.__client : socket.socket = client
+        self.__client.setblocking(False)
+
+        self.inital_req : Request = None
+
+        self.__recv_queue : asyncio.Queue[WSFrame] = asyncio.Queue[WSFrame]()
+        self.__pong_waiters = None
+
+        self.__closed : bool = False
+        self.slugs : dict[str, str] = slugs
+
+        asyncio.create_task(self.__reader())
+
+    def __send_frame(self, opcode: WSOpcode, payload: str | bytes = b"", fin: bool = True):
+        """
+        Utility function used to send frames from server to client
+                    
+        :param opcode: The type of frame sent
+        :type opcode: WSOpcode
+        :param payload: The data sent with the frame
+        :type payload: str | bytes
+        :param fin: If the frame is fragmented
+        :type fin: bool
+        """
+        if self.__closed:
+            raise WSPortalClosedError()
+
+        first_byte = (0x80 if fin else 0) | opcode.value
+
+        length = len(payload)
+        header = bytearray()
+        header.append(first_byte)
+
+        if length < 126:
+            header.append(length)
+        elif length < (1 << 16):
+            header.append(126)
+            header.extend(length.to_bytes(2, "big"))
+        else:
+            header.append(127)
+            header.extend(length.to_bytes(8, "big"))
+
+        data = payload if isinstance(payload, bytes) else payload.encode()
+
+        self.__client.sendall(bytes(header) + data)
+
+    async def __read_exact(self, bufsize : int):
+        loop = asyncio.get_running_loop()
+        data = b""
+        try:
+            while len(data) < bufsize:
+                chunk = await loop.sock_recv(self.__client, bufsize - len(data))
+                if not chunk:
+                    raise ConnectionResetError("Connection Was Reset!")
+                data += chunk
+            return data
+        except Exception as err:
+            raise ConnectionError("Connection Error or Timeout") from err
+
+    async def __reader(self):
+        try:
+            while not self.__closed:
+
+                # Get First part of Header
+                header : bytes = await self.__read_exact(2)
+                length_bytes : bytes = header[1] & 0x7F
+
+                payload_len : int = 0
+
+                # Get payload length
+                if length_bytes == 126:
+                    length_bytes = await self.__read_exact(2)
+                    payload_len = int.from_bytes(length_bytes, "big")
+                elif length_bytes == 127:
+                    length_bytes = await self.__read_exact(8)
+                    payload_len = int.from_bytes(length_bytes, "big")
+                else:
+                    payload_len = length_bytes
+                    length_bytes = b""
+
+
+                # recieve mask if required
+                has_mask : bool = bool(header[1] & 0x80)
+                mask : bytes = await self.__read_exact(4) if has_mask else b""
+
+                # recieve body
+                body : bytes = await self.__read_exact(payload_len)
+
+                # Build WSFrame correctly
+                frame : WSFrame = WSFrame(header + length_bytes + mask + body)
+
+                # react based on opcode
+                if frame.opcode == WSOpcode.PING:
+                    if not frame.fin: # Cannot send fragmented control frames
+                        self.close(1002)
+                    else:
+                        self.__send_frame(
+                            opcode=WSOpcode.PONG,
+                            payload=frame.data
+                                if isinstance(frame.data, bytes)
+                                else frame.data.encode()
+                        )
+                elif frame.opcode == WSOpcode.CLOSE:
+                    self.close()
+                elif frame.opcode == WSOpcode.PONG:
+                    if not self.__pong_waiters.done():
+                        self.__pong_waiters.set_result(True)
+                else:
+                    await self.__recv_queue.put(frame)
+        except Exception:
+            self.close(1011)
+            raise
+
+    @property
+    def closed(self):
+        """
+        Returns if the connection between the client and server is open
+        """
+        return self.__closed
+
+    async def recv(self, timeout: float = None) -> str | bytes:
+        """
+        Recieves a full frame from the client
+
+        If the frame is fragmented, WSPortal.recv() will combine the fragments into a full payload
+
+        :param timeout: If specified, the max time before server raises a WSRecvTimeoutError
+        :type timeout: float
+        :return: The data of the full frame
+        :rtype: str | bytes
+        """
+
+        if self.closed:
+            raise WSPortalClosedError("Tried to recieve from a closed portal!")
+
+        try:
+            frame: WSFrame = await asyncio.wait_for(self.__recv_queue.get(), timeout=timeout)
+
+            if frame.fin: # Unfragmented frame
+                current_time = datetime.now().strftime("%H:%M:%S")
+                ip, _ = self.__client.getpeername()
+
+                print(f"{current_time} Server <-WS- {ip}")
+                return frame.data
+
+            result = frame.data
+            is_text = isinstance(result, str)
+
+            while True:
+                frame = await asyncio.wait_for(self.__recv_queue.get(), timeout=timeout)
+
+                if frame.opcode != WSOpcode.CONTINUATION:
+                    self.close(1002)
+                    raise WSRecvInvalidFrameError("Expected continuation frame")
+
+                result += frame.data if is_text else frame.data.decode()
+
+                if frame.fin:
+                    break
+
+            current_time = datetime.now().strftime("%H:%M:%S")
+            ip, _ = self.__client.getpeername()
+
+            print(f"{current_time} Server <-WS- {ip}")
+
+            return result
+
+        except asyncio.TimeoutError as err:
+            raise WSRecvTimeoutError() from err
+
+    def send(self, payload : str | bytes):
+        """
+        Sends a payload for the client to recieve
+        
+        :param payload: Data to send to the client
+        :type payload: str | bytes
+        """
+
+        if self.closed:
+            raise WSPortalClosedError("Tried to send through a closed portal!")
+
+        opcode = WSOpcode.BINARY if isinstance(payload, bytes) else WSOpcode.TEXT
+
+        self.__send_frame(opcode=opcode, payload=payload)
+
+        current_time = datetime.now().strftime("%H:%M:%S")
+        ip, _ = self.__client.getpeername()
+
+        print(f"{current_time} Server -WS-> {ip}")
+
+    async def ping(self, timeout : float) -> bool:
+        """
+        Pings client to confirm that client is still connected
+        
+        :param timeout: How long before ping times out and returns false
+        :type timeout: float
+        :return: If client returns with a *Pong* client frame
+        :rtype: bool
+        """
+
+        self.__pong_waiters = asyncio.get_running_loop().create_future()
+
+        try:
+            self.__send_frame(WSOpcode.PING)
+
+            result = await asyncio.wait_for(asyncio.shield(self.__pong_waiters), timeout=timeout)
+            return result
+        except asyncio.TimeoutError:
+            return False
+
+        finally:
+            self.__pong_waiters = None
+
+    def close(self, code : int = 1000):
+        """
+        Closes the connection between the server and client using the given close code
+        
+        :param code: The close code the server will send to the client (default 1000)
+        :type code: int
+        """
+
+        if self.closed:
+            return
+
+        self.__send_frame(
+            opcode=WSOpcode.CLOSE,
+            payload=code.to_bytes(2,"big")
+        )
+
+        self.__closed = True
+        self.__client.close()
+
+        current_time = datetime.now().strftime("%H:%M:%S")
+        ip, _ = self.__client.getpeername()
+
+        arrow = "-X->" if code == 1000 else "-!X!->"
+
+        print(f"{current_time} Server {arrow} {ip}")
+
+class WebSocketProtocol(Protocol):
+
+    """
+    The protocol created to handle websocket connections between server and client
+    """
+
+    __WS_GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"
+
+    def __init__(self):
+        self.inital_req : Request = None
+
+    def __compute_accept_key(self, sec_key: str) -> str:
+        sha1 = hashlib.sha1((sec_key + self.__WS_GUID).encode("ascii")).digest()
+        return base64.b64encode(sha1).decode("ascii")
+
+    def get_config_key(self):
+        return "websocket13_config"
+
+    def get_target_endpoints(self) -> list[str]:
+        """
+        :return: All Endpoint functions the WebSocket Protocol looks for
+        :rtype: list[str]
+        """
+        return ["WEBSOCKET"]
+
+    def identify(self, initial_data) -> bool:
+        self.inital_req : Request = Request(initial_data)
+
+        if self.inital_req.headers.get("Connection") != "Upgrade":
+            return False
+
+        if self.inital_req.headers.get("Upgrade", "").lower() != "websocket":
+            return False
+
+        return True
+
+    def handshake(self, client) -> bool:
+        req = self.inital_req
+
+        if req.method != "GET":
+            client.send(Response(400).to_bytes())
+            return False
+
+        if "Host" not in req.headers:
+            client.send(Response(400).to_bytes())
+            return False
+
+        version = req.headers.get("Sec-WebSocket-Version")
+
+        if version != "13":
+            resp = Response(
+                426,
+                headers={
+                    "Upgrade": "websocket",
+                    "Sec-WebSocket-Version": "13"
+                }
+            )
+
+            client.send(resp.to_bytes())
+            return False
+
+        # Create accept key
+
+        key = req.headers.get("Sec-WebSocket-Key")
+        if not key:
+            client.send(Response(400).to_bytes())
+            return False
+
+        try:
+            raw = base64.b64decode(key, validate=True)
+            if len(raw) != 16:
+                raise ValueError("Invalid key")
+        except (binascii.Error, ValueError):
+            client.send(Response(400).to_bytes())
+            return False
+
+        accept_key = self.__compute_accept_key(key)
+
+        # Send protocol transfer success message
+        resp = Response(
+            status_code=101,
+            headers={
+                "Upgrade": "websocket",
+                "Connection": "Upgrade",
+                "Sec-WebSocket-Accept": accept_key,
+            }
+        )
+
+        client.send(resp.to_bytes())
+
+        current_time = datetime.now().strftime("%H:%M:%S")
+        ip, _ = client.getpeername()
+        print(f"{current_time} {self.inital_req.method} {self.inital_req.base_url} <-WS-> {ip}")
+
+        return True
+
+    async def handle(
+        self,
+        client : socket.socket,
+        slugs : dict[str, str],
+        endpoints : dict[str, any]
+    ):
+
+        """
+        Handles connection from client until socket is closed
+        
+        :param client: the socket connection between client and server
+        :param slugs: any slugs they used to get 
+        :param endpoints: Description
+        """
+
+        for endpoint in endpoints:
+            if endpoint in self.get_target_endpoints():
+                portal : WSPortal = WSPortal(slugs=slugs, client=client)
+                await endpoints[endpoint](portal)
+                return
+
+        raise FileNotFoundError("No Websocket Endpoint Found!")

lapis/server_types.py

@@ -0,0 +1,172 @@
+"""
+Module containing all server related types and exceptions
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+import socket
+import json
+import sys
+from typing import get_origin, get_type_hints
+import pathlib
+
+@dataclass
+class ServerConfig:
+    """
+    The class containing all configuration settings for a Lapis server to operate with
+    """
+
+    api_directory : str = "./api"
+    max_request_size : int = 4096
+    server_name : str = "Server"
+    path_script_name : str = "path"
+
+    protocol_configs : dict[str, dict] = field(default_factory=dict)
+
+    @classmethod
+    def from_json(cls, file_path : str | pathlib.Path) -> "ServerConfig":
+        """
+        Generates a ServerConfig object from the json file found at the file path
+        
+        :param file_path: The file path of the json server config
+        :type file_path: str
+        :return: The resulting ServerConfig object generated from the json file
+        :rtype: ServerConfig
+        """
+
+        base_dir = pathlib.Path(sys.argv[0]).parent.resolve()
+        path = (base_dir / file_path).resolve()
+
+        config : ServerConfig = ServerConfig()
+
+        with open(path, 'r', encoding='utf-8') as file:
+            # Read and parse the JSON content from the file
+            data = json.load(file)
+
+            hints = get_type_hints(config.__class__)
+
+            for key, expected_type in hints.items():
+                if key not in data:
+                    continue
+
+                value = data[key]
+
+                if not cls._check_type(value, expected_type):
+                    raise BadConfigError(
+                        f"\"{key}\" must be of type {expected_type.__name__}"
+                    )
+
+                setattr(config, key, value)
+
+        return config
+
+    @classmethod
+    def _check_type(cls, value, expected_type) -> bool:
+        """
+        Returns if a value is an instance of a type while accounting for generics
+        """
+        origin = get_origin(expected_type)
+
+        if origin is None:
+            return isinstance(value, expected_type)
+
+        if origin is dict:
+            return isinstance(value, dict)
+
+        if origin is list:
+            return isinstance(value, list)
+
+        return isinstance(value, origin)
+
+# region Exceptions
+
+class BadRequest(Exception):
+    """
+    An Exception raised when a client request is not formatted correctly
+    """
+
+class BadAPIDirectory(Exception):
+    """
+    An Exception raised when the format of the directory containing all endpoints is incorrect
+    """
+
+class BadConfigError(Exception):
+    """
+    An Exception raised when the format or typing of a Config is given
+    """
+
+class ProtocolEndpointError(Exception):
+    """
+    The exception raised when there is an error with protocol target endpoint functions
+    """
+
+# endregion
+
+class Protocol(ABC):
+    """
+    An abstract class used for the server to be able to handle different protocals (ex: HTTP/1.1)
+    """
+
+    @abstractmethod
+    def get_config_key(self) -> str:
+        """
+        Gathers the keyword used to get the protocol's config from ServerConfig.protocol_configs
+
+        :return: Description
+        :rtype: str
+        """
+
+    @abstractmethod
+    def get_target_endpoints(self) -> list[str]:
+        '''
+        :return: A list of all possible target function names of the protocol
+        :rtype: list[str]
+        '''
+
+        raise NotImplementedError
+
+    @abstractmethod
+    def identify(self, initial_data: bytes) -> bool:
+        """
+        Function called so see if initial request is attempting to upgrade to the given protocol
+        
+        :param initial_data: The initial request from the client
+        :type initial_data: bytes
+        :return: If the initial request is for the given protocol
+        :rtype: bool
+        """
+
+        raise NotImplementedError
+
+    @abstractmethod
+    def handshake(self, client : socket.socket) -> bool:
+        '''
+        Handles the transfering logic between the initial protocol (HTTP/1.1) to the new protocol
+        
+        :param client: The socket connecting the server to the client
+        :type client: socket.socket
+        :return: If the handshake was successful
+        :rtype: bool
+        '''
+
+        raise NotImplementedError
+
+    @abstractmethod
+    async def handle(
+        self,
+        client : socket.socket,
+        slugs: dict[str, str],
+        endpoints: dict[str, any]
+    ):
+        '''
+        Handles the protocol logic and server to client communication
+        
+        :param client: The socket connecting the server to the client
+        :type client: socket.socket
+        :param slugs: Any slugs in the url used to reach the endpoints
+        :type slugs: dict[str, str]
+        :param endpoints: All endpoints of a given url
+        :type endpoints: dict[str, any]
+        '''
+
+        raise NotImplementedError

lapis_api-0.2.0.dist-info/METADATA

@@ -0,0 +1,47 @@
+Metadata-Version: 2.4
+Name: lapis-api
+Version: 0.2.0
+Summary: An organized way to create REST APIs
+Project-URL: Homepage, https://github.com/CQVan/Lapis
+Project-URL: Issues, https://github.com/CQVan/Lapis/issues
+Author: Chandler Van
+License: MIT
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+Lapis is a file-based REST API framework inspired by Modern Serverless Cloud Services
+
+To create a basic Lapis server, create a folder called *api* and create python script named *path.py*
+then within your main folder create a python script to start the server (we will call this script *main.py* in our example)
+
+Your project directory should look like this:
+
+```
+project-root/
+|-- api/
+|  |-- path.py
+`-- main.py
+```
+
+Then within the *api/path.py* file create your first GET api endpoint by adding the following code:
+```py
+from lapis import Response, Request
+
+async def GET (req : Request) -> Response:
+    return Response(status_code=200, body="Hello World!")
+```
+
+Finally by adding the following code to *main.py* and running it:
+```py
+from lapis import Lapis
+
+server = Lapis()
+
+server.run("localhost", 80)
+```
+
+You can now send an HTTP GET request to localhost:80 and recieve the famous **Hello World!** response!

lapis_api-0.2.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+lapis/__init__.py,sha256=5Owb4_8N_pzDnjtfmLErgEvbWcuTYiWWrnvAZwu3aTQ,336
+lapis/lapis.py,sha256=CZNQLdpQmuAbOC2wLbQ6mvaML1OKZ8lqnE4Gm48lbhw,9156
+lapis/server_types.py,sha256=1DuYpgao2uacgHci3c5M0x7dhBpJIyysDx6Bu0DyT1g,5062
+lapis/protocols/http1.py,sha256=EyQWeAPM5tWp4z9z0bi5BgPQ4JFOexDfI9RM9lBNpb4,7920
+lapis/protocols/websocket.py,sha256=Kz0XL8rgxfveU7fy7Xwc7pkFrtj5ywLPXiGpQFjR2AA,16630
+lapis_api-0.2.0.dist-info/METADATA,sha256=bc0OmL62Ryu0zipHknCxVDsIw0sy-_lin9p3MCIJqFU,1398
+lapis_api-0.2.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+lapis_api-0.2.0.dist-info/licenses/LICENSE,sha256=sA2W0Je4lZ-KPmY6VUZ0p4_O6IPLLHJkyHahJnhM_5M,1092
+lapis_api-0.2.0.dist-info/RECORD,,

lapis_api-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

lapis_api-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [2025] [Chandler Van]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.