goosebit 0.1.2__tar.gz → 0.2.1__tar.gz

goosebit-0.2.1/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.1
+Name: goosebit
+Version: 0.2.1
+Summary: 
+Author: Upstream Data
+Author-email: brett@upstreamdata.ca
+Requires-Python: >=3.11,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Provides-Extra: postgresql
+Requires-Dist: aerich (>=0.7.2,<0.8.0)
+Requires-Dist: aiocache (>=0.12.2,<0.13.0)
+Requires-Dist: aiofiles (>=24.1.0,<25.0.0)
+Requires-Dist: argon2-cffi (>=23.1.0,<24.0.0)
+Requires-Dist: asyncpg (>=0.29.0,<0.30.0) ; extra == "postgresql"
+Requires-Dist: fastapi[uvicorn] (>=0.111.0,<0.112.0)
+Requires-Dist: httpx (>=0.27.0,<0.28.0)
+Requires-Dist: itsdangerous (>=2.2.0,<3.0.0)
+Requires-Dist: jinja2 (>=3.1.4,<4.0.0)
+Requires-Dist: joserfc (>=1.0.0,<2.0.0)
+Requires-Dist: libconf (>=2.0.1,<3.0.0)
+Requires-Dist: opentelemetry-distro (>=0.47b0,<0.48)
+Requires-Dist: opentelemetry-exporter-prometheus (>=0.47b0,<0.48)
+Requires-Dist: opentelemetry-instrumentation-fastapi (>=0.47b0,<0.48)
+Requires-Dist: pydantic-settings (>=2.4.0,<3.0.0)
+Requires-Dist: python-multipart (>=0.0.9,<0.0.10)
+Requires-Dist: semver (>=3.0.2,<4.0.0)
+Requires-Dist: tortoise-orm (>=0.21.4,<0.22.0)
+Requires-Dist: websockets (>=12.0,<13.0)
+Description-Content-Type: text/markdown
+
+# gooseBit
+
+<img src="docs/img/goosebit-logo.png" style="width: 100px; height: 100px; display: block;">
+
+---
+
+A simplistic, opinionated remote update server implementing hawkBit™'s [DDI API](https://eclipse.dev/hawkbit/apis/ddi_api/).
+
+## Quick Start
+
+### Installation
+
+1. Install dependencies using [Poetry](https://python-poetry.org/):
+    ```bash
+    poetry install
+    ```
+2. Launch gooseBit:
+    ```bash
+    python main.py
+    ```
+
+### Initial Configuration
+
+Before running gooseBit for the first time, update the default credentials in `settings.yaml`. The default login for testing purposes is:
+
+-   **Username:** `admin@goosebit.local`
+-   **Password:** `admin`
+
+## Assumptions
+
+-   Devices use [SWUpdate](https://swupdate.org) for managing software updates.
+
+## Features
+
+### Device Registry
+
+When a device connects to gooseBit for the first time, it is automatically added to the device registry. The server will then request the device's configuration data, including:
+
+-   `hw_model` and `hw_revision`: Used to match compatible software.
+-   `sw_version`: Indicates the currently installed software version.
+
+The registry tracks each device's status, including the last online timestamp, installed software version, update state, and more.
+
+### Software Repository
+
+Software packages (`*.swu` files) can be hosted directly on the gooseBit server or on an external server. gooseBit parses the software metadata to determine compatibility with specific hardware models and revisions.
+
+### Device Update Modes
+
+Devices can be configured with different update modes. The default mode is `Rollout`.
+
+#### 1. Manual Update to Specified Software
+
+Assign specific software to a device manually. Once installed, no further updates will be triggered.
+
+#### 2. Automatic Update to Latest Software
+
+Automatically updates the device to the latest compatible software, based on the reported `hw_model` and `hw_revision`. Note: versions are interpreted as [SemVer](https://semver.org) versions.
+
+#### 3. Software Rollout
+
+Rollouts target all devices with a specified "feed" value, ensuring that the assigned software is installed on all matching devices. Rollouts also track success and error rates, with future plans for automatic aborts. If multiple rollouts exist for the same feed, the most recent rollout takes precedence.
+
+### Pause Updates
+
+Devices can be pinned to their current software version, preventing any updates from being applied.
+
+### Real-time Update Logs
+
+While updates are in progress, gooseBit captures real-time logs, which are accessible through the device repository.
+
+## Development
+
+### Database
+
+Create or upgrade database
+
+```bash
+poetry run aerich upgrade
+```
+
+After a model change create the migration
+
+```bash
+poetry run aerich migrate
+```
+
+### Code formatting and linting
+
+Code is formatted using different tools
+
+-   black and isort for `*.py`
+-   biomejs for `*.js`, `*.json`
+-   prettier for `*.html`, `*.md`, `*.yml`, `*.yaml`
+
+Code is linted using different tools as well
+
+-   flake8 for `*.py`
+-   biomejs for `*.js`
+
+Best to have pre-commit install git hooks that run all those tools before a commit:
+
+```bash
+poetry run pre-commit install
+```
+
+To manually apply the hooks to all files use:
+
+```bash
+pre-commit run --all-files
+```
+
+### Testing
+
+Tests are implemented using pytest. To run all tests
+
+```bash
+poetry run pytest
+```
+
+### Structure
+
+The structure of gooseBit is as follows:
+
+-   `api`: Files for the API.
+-   `ui`: Files for the UI.
+    -   `bff`: Backend for frontend API.
+    -   `static`: Static files.
+    -   `templates`: Jinja2 formatted templates.
+    -   `nav`: Navbar handler.
+-   `updater`: DDI API handler and device update manager.
+-   `updates`: SWUpdate file parsing.
+-   `realtime`: Realtime API functionality with websockets.
+-   `auth`: Authentication functions and permission handling.
+-   `models`: Database models.
+-   `db`: Database config and initialization.
+-   `schema`: Pydantic models used for API type hinting.
+-   `settings`: Settings loader and handler.
+-   `telemetry`: Telemetry data handlers.
+-   `routes`: Routes for a giving endpoint, including the router.
+

goosebit-0.2.1/README.md

@@ -0,0 +1,140 @@
+# gooseBit
+
+<img src="docs/img/goosebit-logo.png" style="width: 100px; height: 100px; display: block;">
+
+---
+
+A simplistic, opinionated remote update server implementing hawkBit™'s [DDI API](https://eclipse.dev/hawkbit/apis/ddi_api/).
+
+## Quick Start
+
+### Installation
+
+1. Install dependencies using [Poetry](https://python-poetry.org/):
+    ```bash
+    poetry install
+    ```
+2. Launch gooseBit:
+    ```bash
+    python main.py
+    ```
+
+### Initial Configuration
+
+Before running gooseBit for the first time, update the default credentials in `settings.yaml`. The default login for testing purposes is:
+
+-   **Username:** `admin@goosebit.local`
+-   **Password:** `admin`
+
+## Assumptions
+
+-   Devices use [SWUpdate](https://swupdate.org) for managing software updates.
+
+## Features
+
+### Device Registry
+
+When a device connects to gooseBit for the first time, it is automatically added to the device registry. The server will then request the device's configuration data, including:
+
+-   `hw_model` and `hw_revision`: Used to match compatible software.
+-   `sw_version`: Indicates the currently installed software version.
+
+The registry tracks each device's status, including the last online timestamp, installed software version, update state, and more.
+
+### Software Repository
+
+Software packages (`*.swu` files) can be hosted directly on the gooseBit server or on an external server. gooseBit parses the software metadata to determine compatibility with specific hardware models and revisions.
+
+### Device Update Modes
+
+Devices can be configured with different update modes. The default mode is `Rollout`.
+
+#### 1. Manual Update to Specified Software
+
+Assign specific software to a device manually. Once installed, no further updates will be triggered.
+
+#### 2. Automatic Update to Latest Software
+
+Automatically updates the device to the latest compatible software, based on the reported `hw_model` and `hw_revision`. Note: versions are interpreted as [SemVer](https://semver.org) versions.
+
+#### 3. Software Rollout
+
+Rollouts target all devices with a specified "feed" value, ensuring that the assigned software is installed on all matching devices. Rollouts also track success and error rates, with future plans for automatic aborts. If multiple rollouts exist for the same feed, the most recent rollout takes precedence.
+
+### Pause Updates
+
+Devices can be pinned to their current software version, preventing any updates from being applied.
+
+### Real-time Update Logs
+
+While updates are in progress, gooseBit captures real-time logs, which are accessible through the device repository.
+
+## Development
+
+### Database
+
+Create or upgrade database
+
+```bash
+poetry run aerich upgrade
+```
+
+After a model change create the migration
+
+```bash
+poetry run aerich migrate
+```
+
+### Code formatting and linting
+
+Code is formatted using different tools
+
+-   black and isort for `*.py`
+-   biomejs for `*.js`, `*.json`
+-   prettier for `*.html`, `*.md`, `*.yml`, `*.yaml`
+
+Code is linted using different tools as well
+
+-   flake8 for `*.py`
+-   biomejs for `*.js`
+
+Best to have pre-commit install git hooks that run all those tools before a commit:
+
+```bash
+poetry run pre-commit install
+```
+
+To manually apply the hooks to all files use:
+
+```bash
+pre-commit run --all-files
+```
+
+### Testing
+
+Tests are implemented using pytest. To run all tests
+
+```bash
+poetry run pytest
+```
+
+### Structure
+
+The structure of gooseBit is as follows:
+
+-   `api`: Files for the API.
+-   `ui`: Files for the UI.
+    -   `bff`: Backend for frontend API.
+    -   `static`: Static files.
+    -   `templates`: Jinja2 formatted templates.
+    -   `nav`: Navbar handler.
+-   `updater`: DDI API handler and device update manager.
+-   `updates`: SWUpdate file parsing.
+-   `realtime`: Realtime API functionality with websockets.
+-   `auth`: Authentication functions and permission handling.
+-   `models`: Database models.
+-   `db`: Database config and initialization.
+-   `schema`: Pydantic models used for API type hinting.
+-   `settings`: Settings loader and handler.
+-   `telemetry`: Telemetry data handlers.
+-   `routes`: Routes for a giving endpoint, including the router.

goosebit-0.2.1/goosebit/__init__.py

@@ -0,0 +1,96 @@
+import importlib.metadata
+from contextlib import asynccontextmanager
+from typing import Annotated
+
+from fastapi import Depends, FastAPI
+from fastapi.openapi.docs import get_swagger_ui_html
+from fastapi.requests import Request
+from fastapi.responses import RedirectResponse
+from fastapi.security import OAuth2PasswordRequestForm
+from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor as Instrumentor
+
+from goosebit import api, db, realtime, ui, updater
+from goosebit.api.telemetry import metrics
+from goosebit.auth import get_user_from_request, login_user, redirect_if_authenticated
+from goosebit.ui.nav import nav
+from goosebit.ui.static import static
+from goosebit.ui.templates import templates
+
+
+@asynccontextmanager
+async def lifespan(_: FastAPI):
+    await db.init()
+    await metrics.init()
+    yield
+    await db.close()
+
+
+app = FastAPI(
+    title="gooseBit",
+    summary="A simplistic, opinionated remote update server implementing hawkBit™'s DDI API.",
+    version=importlib.metadata.version("goosebit"),
+    lifespan=lifespan,
+    license_info={
+        "name": "Apache 2.0",
+        "identifier": "Apache-2.0",
+    },
+    redoc_url=None,
+    docs_url=None,
+    openapi_tags=[
+        {
+            "name": "login",
+            "description": "API authentication.  "
+            "Can be used in the `authorization` header, in the format `{token_type} {access_token}`.",
+        }
+    ],
+)
+app.include_router(updater.router)
+app.include_router(ui.router)
+app.include_router(api.router)
+app.include_router(realtime.router)
+app.mount("/static", static, name="static")
+Instrumentor.instrument_app(app)
+
+
+@app.middleware("http")
+async def attach_user(request: Request, call_next):
+    request.scope["user"] = await get_user_from_request(request)
+    return await call_next(request)
+
+
+@app.middleware("http")
+async def attach_nav(request: Request, call_next):
+    request.scope["nav"] = nav.get()
+    return await call_next(request)
+
+
+@app.get("/", include_in_schema=False)
+def root_redirect(request: Request):
+    return RedirectResponse(request.url_for("ui_root"))
+
+
+@app.get("/login", include_in_schema=False, dependencies=[Depends(redirect_if_authenticated)])
+async def login_get(request: Request):
+    return templates.TemplateResponse(request, "login.html.jinja")
+
+
+@app.post("/login", tags=["login"])
+async def login_post(form_data: Annotated[OAuth2PasswordRequestForm, Depends()]):
+    return {"access_token": login_user(form_data.username, form_data.password), "token_type": "bearer"}
+
+
+@app.get("/logout", include_in_schema=False)
+async def logout(request: Request):
+    resp = RedirectResponse(request.url_for("login_get"), status_code=302)
+    resp.delete_cookie(key="session_id")
+    return resp
+
+
+@app.get("/docs")
+async def swagger_docs(request: Request):
+    return get_swagger_ui_html(
+        title="gooseBit docs",
+        openapi_url="/openapi.json",
+        swagger_favicon_url=str(request.url_for("static", path="/favicon.svg")),
+        swagger_ui_parameters={"operationsSorter": "alpha"},
+    )

goosebit-0.2.1/goosebit/__main__.py

@@ -0,0 +1,7 @@
+import uvicorn
+
+from goosebit import app
+from goosebit.settings import config
+
+if __name__ == "__main__":
+    uvicorn.run(app, host="0.0.0.0", port=config.port)

goosebit-0.2.1/goosebit/api/responses.py

@@ -0,0 +1,5 @@
+from pydantic import BaseModel
+
+
+class StatusResponse(BaseModel):
+    success: bool

goosebit-0.2.1/goosebit/api/routes.py

@@ -0,0 +1,9 @@
+from fastapi import APIRouter, Depends
+
+from goosebit.auth import validate_current_user
+
+from . import telemetry, v1
+
+router = APIRouter(prefix="/api", dependencies=[Depends(validate_current_user)])
+router.include_router(telemetry.router)
+router.include_router(v1.router)

goosebit-0.1.2/goosebit/telemetry/__init__.py → goosebit-0.2.1/goosebit/api/telemetry/metrics.py

@@ -2,13 +2,19 @@ from opentelemetry import metrics
 from opentelemetry.sdk.metrics import MeterProvider
 from opentelemetry.sdk.resources import SERVICE_NAME, Resource
 
-from goosebit import settings
+from goosebit.settings import USERS, config
 
 from . import prometheus
 
+readers = []
+
+if config.metrics.prometheus.enable:
+    readers.append(prometheus.reader)
+
+
 resource = Resource(attributes={SERVICE_NAME: "goosebit"})
 
-provider = MeterProvider(resource=resource, metric_readers=[prometheus.reader])
+provider = MeterProvider(resource=resource, metric_readers=readers)
 metrics.set_meter_provider(provider)
 
 meter = metrics.get_meter("goosebit.meter")
@@ -25,4 +31,4 @@ users_count = meter.create_gauge(
 
 
 async def init():
-    users_count.set(len(settings.USERS))
+    users_count.set(len(USERS))

goosebit-0.2.1/goosebit/api/telemetry/prometheus/__init__.py

@@ -0,0 +1,2 @@
+from .readers import reader  # noqa: F401
+from .routes import router  # noqa: F401

goosebit-0.2.1/goosebit/api/telemetry/prometheus/readers.py

@@ -0,0 +1,3 @@
+from opentelemetry.exporter.prometheus import PrometheusMetricReader
+
+reader = PrometheusMetricReader()

goosebit-0.2.1/goosebit/api/telemetry/prometheus/routes.py

@@ -0,0 +1,18 @@
+from fastapi import APIRouter, Header
+from fastapi.requests import Request
+from fastapi.responses import Response
+from prometheus_client import REGISTRY
+from prometheus_client.exposition import _bake_output
+
+router = APIRouter(prefix="/prometheus", tags=["prometheus"])
+
+
+@router.get("/metrics")
+async def metrics(
+    request: Request, accept: list[str] = Header(None), accept_encoding: list[str] = Header(None)
+) -> Response:
+    status, http_headers, output = _bake_output(
+        REGISTRY, ",".join(accept), ",".join(accept_encoding), request.query_params, False
+    )
+    headers = {h[0]: h[1] for h in http_headers}
+    return Response(content=output, headers=headers)

goosebit-0.2.1/goosebit/api/telemetry/routes.py

@@ -0,0 +1,9 @@
+from fastapi import APIRouter
+
+from goosebit.settings import config
+
+from . import prometheus
+
+router = APIRouter(prefix="/telemetry")
+if config.metrics.prometheus.enable:
+    router.include_router(prometheus.router)

goosebit-0.2.1/goosebit/api/v1/devices/__init__.py

@@ -0,0 +1 @@
+from .routes import router  # noqa : F401

goosebit-0.2.1/goosebit/api/v1/devices/device/__init__.py

@@ -0,0 +1 @@
+from .routes import router  # noqa : F401

goosebit-0.2.1/goosebit/api/v1/devices/device/responses.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+from goosebit.schema.devices import DeviceSchema
+
+
+class DeviceLogResponse(BaseModel):
+    log: str | None
+
+
+class DeviceResponse(DeviceSchema):
+    pass

goosebit-0.2.1/goosebit/api/v1/devices/device/routes.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, Security
+from fastapi.requests import Request
+
+from goosebit.api.v1.devices.device.responses import DeviceLogResponse, DeviceResponse
+from goosebit.auth import validate_user_permissions
+from goosebit.updater.manager import UpdateManager, get_update_manager
+
+router = APIRouter(prefix="/{dev_id}")
+
+
+@router.get(
+    "",
+    dependencies=[Security(validate_user_permissions, scopes=["home.read"])],
+)
+async def device_get(_: Request, updater: UpdateManager = Depends(get_update_manager)) -> DeviceResponse:
+    return await DeviceResponse.convert(await updater.get_device())
+
+
+@router.get(
+    "/log",
+    dependencies=[Security(validate_user_permissions, scopes=["home.read"])],
+)
+async def device_logs(_: Request, updater: UpdateManager = Depends(get_update_manager)) -> DeviceLogResponse:
+    device = await updater.get_device()
+    return DeviceLogResponse(log=device.last_log)

goosebit-0.2.1/goosebit/api/v1/devices/requests.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+
+class DevicesDeleteRequest(BaseModel):
+    devices: list[str]

goosebit-0.2.1/goosebit/api/v1/devices/responses.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+import asyncio
+
+from pydantic import BaseModel
+
+from goosebit.db.models import Device
+from goosebit.schema.devices import DeviceSchema
+
+
+class DevicesResponse(BaseModel):
+    devices: list[DeviceSchema]
+
+    @classmethod
+    async def convert(cls, devices: list[Device]):
+        return cls(devices=await asyncio.gather(*[DeviceSchema.convert(d) for d in devices]))

goosebit-0.2.1/goosebit/api/v1/devices/routes.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from fastapi import APIRouter, Security
+from fastapi.requests import Request
+
+from goosebit.api.responses import StatusResponse
+from goosebit.auth import validate_user_permissions
+from goosebit.db.models import Device
+from goosebit.updater.manager import delete_devices
+
+from . import device
+from .requests import DevicesDeleteRequest
+from .responses import DevicesResponse
+
+router = APIRouter(prefix="/devices", tags=["devices"])
+
+
+@router.get(
+    "",
+    dependencies=[Security(validate_user_permissions, scopes=["home.read"])],
+)
+async def devices_get(_: Request) -> DevicesResponse:
+    return await DevicesResponse.convert(await Device.all().prefetch_related("assigned_software", "hardware"))
+
+
+@router.delete(
+    "",
+    dependencies=[Security(validate_user_permissions, scopes=["device.delete"])],
+)
+async def devices_delete(_: Request, config: DevicesDeleteRequest) -> StatusResponse:
+    await delete_devices(config.devices)
+    return StatusResponse(success=True)
+
+
+router.include_router(device.router)

goosebit-0.2.1/goosebit/api/v1/download/__init__.py

@@ -0,0 +1 @@
+from .routes import router  # noqa : F401

goosebit-0.2.1/goosebit/api/v1/download/routes.py

@@ -0,0 +1,22 @@
+from fastapi import APIRouter, HTTPException
+from fastapi.requests import Request
+from fastapi.responses import FileResponse, RedirectResponse
+
+from goosebit.db.models import Software
+
+router = APIRouter(prefix="/download", tags=["download"])
+
+
+@router.get("/{file_id}")
+async def download_file(_: Request, file_id: int):
+    software = await Software.get_or_none(id=file_id)
+    if software is None:
+        raise HTTPException(404)
+    if software.local:
+        return FileResponse(
+            software.path,
+            media_type="application/octet-stream",
+            filename=software.path.name,
+        )
+    else:
+        return RedirectResponse(url=software.uri)

goosebit-0.2.1/goosebit/api/v1/rollouts/requests.py

@@ -0,0 +1,16 @@
+from pydantic import BaseModel
+
+
+class RolloutsPutRequest(BaseModel):
+    name: str
+    feed: str
+    software_id: int
+
+
+class RolloutsPatchRequest(BaseModel):
+    ids: list[int]
+    paused: bool
+
+
+class RolloutsDeleteRequest(BaseModel):
+    ids: list[int]

goosebit-0.2.1/goosebit/api/v1/rollouts/responses.py

@@ -0,0 +1,19 @@
+import asyncio
+
+from pydantic import BaseModel
+
+from goosebit.api.responses import StatusResponse
+from goosebit.db.models import Rollout
+from goosebit.schema.rollouts import RolloutSchema
+
+
+class RolloutsPutResponse(StatusResponse):
+    id: int
+
+
+class RolloutsResponse(BaseModel):
+    rollouts: list[RolloutSchema]
+
+    @classmethod
+    async def convert(cls, devices: list[Rollout]):
+        return cls(rollouts=await asyncio.gather(*[RolloutSchema.convert(d) for d in devices]))