cal-docs-server 3.0.0b1__py3-none-any.whl

cal_docs_server/web_server.py

@@ -0,0 +1,217 @@
+# ----------------------------------------------------------------------------------------
+#   web_server
+#   ----------
+#
+#   Runs the web server using aiohttp
+#
+#   License
+#   -------
+#   MIT License - Copyright 2025-2026 Cyber Assessment Labs
+#
+#   Authors
+#   -------
+#   bena
+#
+#   Version History
+#   ---------------
+#   Mar 2024 - Created
+#   Dec 2025 - New version 2
+# ----------------------------------------------------------------------------------------
+
+# ----------------------------------------------------------------------------------------
+#   Imports
+# ----------------------------------------------------------------------------------------
+
+import importlib.resources
+import mimetypes
+import os
+from collections.abc import Awaitable
+from collections.abc import Callable
+from functools import partial
+from aiohttp import web
+from . import api
+from . import async_file
+from . import render_md
+from .cache_render_index import cache_render_index
+from .version import VERSION_STR
+
+# ----------------------------------------------------------------------------------------
+#   Types
+# ----------------------------------------------------------------------------------------
+
+Handler = Callable[[web.Request], Awaitable[web.StreamResponse]]
+
+# ----------------------------------------------------------------------------------------
+#   Functions
+# ----------------------------------------------------------------------------------------
+
+
+# ----------------------------------------------------------------------------------------
+async def launch_web_server(
+    root_directory: str,
+    port: int,
+    server_name: str = "Documents Server",
+    tokens_file: str | None = None,
+    base_url: str | None = None,
+) -> None:
+    """
+    Launches the web server listening on `port` and serving from `root_directory`
+    """
+
+    app = web.Application(middlewares=[_set_server_name])
+    app["server_name"] = server_name
+    app["tokens_file"] = tokens_file  # Tokens loaded dynamically with 5s cache
+    # Strip trailing slash from base_url if provided
+    app["base_url"] = base_url.rstrip("/") if base_url else ""
+
+    # API routes (must be registered before the catch-all static route)
+    api.setup_api_routes(app, root_directory)
+
+    app.router.add_get("/", partial(_serve_index, root_directory=root_directory))
+    app.router.add_get("/help", _serve_help)
+
+    app.router.add_get(
+        "/{path:.*}", partial(_serve_static, root_directory=root_directory)
+    )
+
+    runner = web.AppRunner(app)
+    await runner.setup()
+    server = web.TCPSite(runner, "0.0.0.0", port)
+    await server.start()
+
+    print(f"CAL Docs Server started on port: {port}")
+
+    if not app["tokens_file"]:
+        print("Warning: No API tokens configured - uploads will be rejected")
+
+
+# ----------------------------------------------------------------------------------------
+#   Private Functions
+# ----------------------------------------------------------------------------------------
+
+
+# ----------------------------------------------------------------------------------------
+@web.middleware
+async def _set_server_name(
+    request: web.Request, handler: Handler
+) -> web.StreamResponse:
+    """
+    This replaces the Server header with our name. Odd that its not just a parameter
+    to pass to `web.Application` but apparently it isn't.
+    """
+
+    response = await handler(request)
+    response.headers["Server"] = f"cal-docs-server/{VERSION_STR}"
+    return response
+
+
+# ----------------------------------------------------------------------------------------
+async def _serve_static(request: web.Request, root_directory: str) -> web.Response:
+    """
+    Handles requests for the static files.
+    """
+
+    path: str = request.match_info.get("path", "").replace("%20", " ")
+    if ".." in path:
+        return web.Response(status=400, text="Invalid URL\n")
+
+    # Check if this path should be redirected to a versioned directory
+    # Get the first component of the path (the package name)
+    path_parts = path.split("/")
+    base_package = path_parts[0] if path_parts else ""
+
+    # Check if we have a version redirect for this package
+    version_redirects = request.app.get("version_redirects", {})
+    if base_package and base_package in version_redirects:
+        # Redirect to the versioned directory
+        versioned_dir = version_redirects[base_package]
+        # Replace the first path component with the versioned directory
+        path_parts[0] = versioned_dir
+        path = "/".join(path_parts)
+
+    file_path: str = os.path.join(root_directory, path)
+
+    if os.path.isdir(file_path):
+        if not request.path.endswith("/"):
+            # If URL doesn't end with a slash we send it a redirect
+            return web.HTTPFound(location=request.path + "/")
+
+        # A directory specified means we want to get index.html or index.md
+        html_file_path = os.path.join(file_path, "index.html")
+        md_file_path = os.path.join(file_path, "index.md")
+        if os.path.isfile(html_file_path):
+            file_path = html_file_path
+        elif os.path.isfile(md_file_path):
+            file_path = md_file_path
+
+    if os.path.isfile(file_path):
+        try:
+            async with async_file.open_binary(file_path, "rb") as f:
+                file_contents = await f.read()
+            if file_path.endswith(".md"):
+                # Convert MarkDown to html on the fly
+                content_type = "text/html"
+                file_contents = await render_md.md_to_html(file_contents)
+            else:
+                content_type = (
+                    mimetypes.guess_type(file_path)[0] or "application/octet-stream"
+                )
+            response_page = web.Response(body=file_contents, content_type=content_type)
+            return response_page
+        except OSError:
+            # File became unavailable between check and read
+            return web.HTTPNotFound(text="404 Not found\n")
+
+    # We haven't served a response yet. So return a 404
+    return web.HTTPNotFound(text="404 Not found\n")
+
+
+# ----------------------------------------------------------------------------------------
+async def _serve_index(request: web.Request, root_directory: str) -> web.Response:
+    """
+    Handles requests for the main index page.
+    """
+
+    try:
+        server_name = request.app.get("server_name", "Documents Server")
+        text, version_redirects = await cache_render_index(
+            root_directory=root_directory, server_name=server_name
+        )
+
+        # Store version redirects in the app for use by _serve_static
+        request.app["version_redirects"] = version_redirects
+
+        response_page = web.Response(body=text, content_type="text/html")
+        return response_page
+    except Exception as e:
+        return web.Response(
+            text=f"Error loading index: {e}\n",
+            status=500,
+            content_type="text/plain",
+        )
+
+
+# ----------------------------------------------------------------------------------------
+async def _serve_help(_request: web.Request) -> web.Response:
+    """
+    Handles requests for the /help page - serves the help markdown file from resources.
+    """
+
+    try:
+        file_folder = importlib.resources.files("cal_docs_server.resources")
+        file_path = os.path.join(str(file_folder), "help.md")
+
+        async with async_file.open_binary(file_path, "rb") as f:
+            file_contents = await f.read()
+
+        # Render markdown to HTML
+        html_content = await render_md.md_to_html(file_contents)
+
+        response_page = web.Response(body=html_content, content_type="text/html")
+        return response_page
+    except Exception as e:
+        return web.Response(
+            text=f"Error loading help: {e}\n",
+            status=500,
+            content_type="text/plain",
+        )

cal_docs_server-3.0.0b1.dist-info/METADATA

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: cal-docs-server
+Version: 3.0.0b1
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.14
+Requires-Dist: aiohttp>=3.9.3
+Requires-Dist: json5>=0.9.18
+Requires-Dist: markdown>=3.5.2
+Requires-Dist: pyyaml>=6.0.1
+Requires-Dist: types-markdown>=3.5
+Requires-Dist: types-pyyaml>=6.0.12.12

cal_docs_server-3.0.0b1.dist-info/RECORD

@@ -0,0 +1,24 @@
+cal_docs_server/.gitignore,sha256=M4fmG7SHXNkkyUIiMjvf8SOuIU6bfWxJC-85lUBOxaM,23
+cal_docs_server/__init__.py,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+cal_docs_server/__main__.py,sha256=Cfaum1RNvOfZ5ISXMc39h1pjICeMdyWL4Vu7lej3l7A,1611
+cal_docs_server/_version.py,sha256=h20xb9c3QtHKsuqaoIU5c8oFHkh-1bywwxPhXtsg7qo,173
+cal_docs_server/api.py,sha256=QWJsMtNFkdHCaMJHq0hykZxLQYwN5ByWm621BHsoMMo,22080
+cal_docs_server/async_file.py,sha256=QdfKZawneR72KmRE93uZJBbaMwWiIKmm7_7gFPtSxEU,3648
+cal_docs_server/auth.py,sha256=G0jdYXoQctybWOOVbY0MlxbQ0n-TjWP6D0gz1M9tGjA,7994
+cal_docs_server/cache_render_index.py,sha256=72MnpqGnUUzJ4_ezyrObQAHGPE3Qg1N5HdjGo0_xw3A,3451
+cal_docs_server/index_docs.py,sha256=QfkKgTojXRoC9kwwpJ29ArB_qZrn203T6PAu6M0OpO4,15560
+cal_docs_server/main.py,sha256=djePJTuz_XHrzECA6ewFnjOfwe6mSc7lZikDi6R37So,5890
+cal_docs_server/render_index.py,sha256=SRBMrVoY76XjWoj-K7lgiI5fadNkNLVDvU7EQE4M_wg,5842
+cal_docs_server/render_md.py,sha256=j4fm0M1xgMJNiz1yhcUV4bm8duC-3TN2bbzAIhYLjJI,2813
+cal_docs_server/version.py,sha256=9Pa48sDghqw_GgZCOjHyyvC2zYJvy0lVImJw3sxceug,1111
+cal_docs_server/web_server.py,sha256=eBLoPJCJbaDIzwkjt7zCzaHMpBIZU0DUpZvzBQkgQUc,7826
+cal_docs_server/resources/__init__.py,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+cal_docs_server/resources/help.md,sha256=pcfQWd0ZX3AhBESzSyAM8JfBFPZh2m7c_Gettyz2wpQ,4849
+cal_docs_server/resources/index_template.html,sha256=6EvV4sH8JpEaWBWXzhOXZoBuHJUOf301BCjk4TxHlj8,15797
+cal_docs_server/resources/md_template.html,sha256=HZdx_qnnbWbvnTR1kmDGhKNODJOySPF9NTaRP_tbkfQ,5399
+cal_docs_server/resources/openapi.yaml,sha256=wsUTcx31WE6oyv7Usev7pYp8KV2v9paqcy_KpScY_Ro,7931
+cal_docs_server-3.0.0b1.dist-info/METADATA,sha256=kbR9iZ0U3fMgnoxYwHFe7MYW27dOyYcgrXHn1SDWb58,324
+cal_docs_server-3.0.0b1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+cal_docs_server-3.0.0b1.dist-info/entry_points.txt,sha256=irb15ryE9DMciKfJvVWP25b3zTxiotoTeVvwtl4ZYJU,61
+cal_docs_server-3.0.0b1.dist-info/licenses/LICENSE,sha256=2QIKIIT_RVuBkU1cGnZ7wZ-E6j1WOqFDnfzofJfiH64,1083
+cal_docs_server-3.0.0b1.dist-info/RECORD,,

cal_docs_server-3.0.0b1.dist-info/WHEEL

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

cal_docs_server-3.0.0b1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+cal-docs-server = cal_docs_server:__main__

cal_docs_server-3.0.0b1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Cyber Assessment Labs
+
+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.