django-widget-hub

Declare a dashboard widget once in Python, and get parameter validation, caching, owner-scoped CRUD, an /about.json discovery endpoint, django-ninja and DRF adapters, and a ready-made front.

# settings.py: INSTALLED_APPS += ["widget_hub"]   urls.py: path("", include("widget_hub.urls"))
from widget_hub import Service, Widget, params, register


@register
class CityWeather(Widget):
    service = Service("weather")
    name = "city_weather"
    params = [params.String("city", max_length=100)]

    def fetch(self, params, context):
        return {"city": params["city"], "temperature": 21}


# template: {% load widget_hub %}{% dashboard %}

Why this exists

This package comes out of the Epitech Dashboard project, a Django + React app where users place widgets (weather, RSS, GitHub, Steam…) on a grid and the grading script reads /about.json. In that codebase, adding one widget meant editing three or four places that nothing kept in sync:

1. services/registry.py: a hand-written dict that /about.json returns as-is;
2. services/api.py: a dedicated route that calls the external API and shapes the response;
3. WidgetInstance.params: a free-form JSON field, "not yet validated against the registry";
4. the React component that knows the route, the params and the response shape.

Before, for the RSS widget (abridged from the original code):

# services/registry.py
{
    "name": "rss",
    "widgets": [
        {
            "name": "article_list",
            "description": "Display the latest articles of an RSS feed",
            "params": [{"name": "link", "type": "string"}, {"name": "number", "type": "integer"}],
        }
    ],
}


# services/api.py
@api.get("/rss")
def rss(request, link: str, number: int = 5):
    if not 1 <= number <= 20:
        return api.create_response(
            request, {"error": "number must be between 1 and 20"}, status=400
        )
    try:
        url = link
        for _ in range(4):  # hand-made SSRF check + redirect loop
            if not _is_public_url(url):
                ...
            response = requests.get(url, timeout=10, allow_redirects=False)
            ...
    except (requests.RequestException, ValueError) as error:
        return api.create_response(request, {"error": "...", "details": str(error)}, status=503)

After, the whole widget:

@register
class ArticleList(Widget):
    service = rss
    name = "article_list"
    description = "Display the latest articles of an RSS feed"
    params = [params.Url("link"), params.Integer("number", min_value=1, max_value=20, default=5)]

    def fetch(self, params, context):
        return parse_feed(safe_fetch(params["link"]).content, params["number"])

/about.json, validation, the route, owner scoping, caching, error handling and the settings form all derive from that declaration. The scattered version caused real bugs:

• two registry entries were both named "weather", so the grader would count one service and a widget was hidden; it was only caught by reading the output (project changelog);
• the registry said "naza_picture" while the route was /nasa_picture: a typo nothing could detect, since the registry and the routes are unrelated code;
• stored params were never validated, so a widget could be saved with values its route rejected;
• error responses carried str(exception) to the browser, leaking upstream URLs and library messages;
• the SSRF check resolved the host, then requests resolved it again (DNS rebinding window), and client.host trusted a client-supplied X-Forwarded-For;
• the token encryption key was sha256(SECRET_KEY): rotating SECRET_KEY silently destroyed every stored token;
• the clock widget was declared in the registry with no backend route at all: nothing checks that a declared widget can actually be served.

Existing solutions

Researched on PyPI and GitHub on 2026-10-15 (details and method in docs/research.md).

None offers "declare once → validation + owner-scoped CRUD + caching + discovery endpoint + REST adapters". Whether some of them could be bent to it with custom code was not evaluated.

Features

• Declarative widgets: Service, Widget, typed params, @register; duplicate names stop the server at startup.
• Validation of every parameter (type, required, bounds, choices, URL shape) with one precise message per field, before fetch() runs.
• Storage: a WidgetInstance model on AUTH_USER_MODEL, migrations and admin included.
• Owner scoping everywhere: another user's instance is a 404.
• Caching and limits: Django cache per (widget, params), min/max refresh rate, per-call timeout, cap on concurrent upstream calls.
• One error contract across all endpoints; exception details stay in logs.
• /about.json in the Epitech format, generated from the registry.
• Adapters for django-ninja and DRF, plus a session JSON API for the built-in front.
• Security helpers: safe_fetch() (SSRF-safe HTTP) and an encrypted credential store.
• Built-in front: {% dashboard %} with drag/resize, generated settings forms, keyboard support, light/dark themes, no build step.

Installation

pip install django-widget-hub            # core
pip install "django-widget-hub[ninja]"   # + django-ninja adapter
pip install "django-widget-hub[drf]"     # + Django REST framework adapter

Supports Django 5.2 LTS, 6.0 and 6.1, with the Python versions each supports (3.10–3.14 for 5.2, 3.12–3.14 for 6.x).

INSTALLED_APPS = [..., "widget_hub"]
# urls.py
urlpatterns = [..., path("", include("widget_hub.urls"))]

Then python manage.py migrate. Put widgets in <your_app>/widgets.py: those modules are imported automatically at startup.

HTTP (safe_fetch), caching, threading and validation use the standard library and Django.

Configuration

All settings live in one optional dict, WIDGET_HUB = {...}. Unknown keys and bad values fail manage.py check (widget_hub.E001–E006).

The default owner is request.auth when an API framework set it to a user, else request.user. action is one of catalog, list, create, retrieve, update, delete, fetch, credentials.

Declaring widgets

# myapp/widgets.py
from widget_hub import Service, Widget, WidgetError, params, register
from widget_hub.security import safe_fetch

weather = Service("weather", description="Open-Meteo forecasts")


@register
class CityForecast(Widget):
    service = weather  # required; reuse the same Service object per service
    name = "city_forecast"  # required; unique within the service
    description = "Daily forecast for a city"
    default_refresh_rate = 600  # seconds, kept within MIN/MAX_REFRESH_RATE
    params = [
        params.String("city", max_length=100),
        params.Integer("days", min_value=1, max_value=16, default=5),
    ]

    def fetch(self, params, context):
        # params: validated values, defaults applied. context: FetchContext(owner, instance_id,
        # credential). Return anything JSON-serialisable.
        response = safe_fetch("https://api.example.com/forecast", params=params)
        if response.status == 404:
            raise WidgetError("City not found.", 404)
        return response.json()

Two widgets with the same service and name, or two Service objects with the same name, stop the server with an ImproperlyConfigured error naming both declarations. Other class attributes: cache_per_owner (results depend on the user) and uses_credential (see Security).

Params reference

Every param also takes required=True, default=, label=, help_text=; defaults are validated when the class is defined. Widget.validate(data) returns the cleaned dict or raises ParamValidationError whose errors maps each parameter (or "__all__") to one message, e.g. {"days": "Must be less than or equal to 16.", "colour": "Unknown parameter."}. Widget.schema() is the JSON description used by the front and API clients.

Caching and rate limits

fetch() results go through Django's cache framework (CACHE_ALIAS; Django's default backend is LocMem, use Redis or Memcached to share it between processes). The key is (service, widget, normalised params), so a hundred users showing the weather in Paris cause one upstream call per refresh period; set cache_per_owner = True when the data depends on the user. An entry is reused while it is younger than the instance's refresh_rate, which must stay within MIN_REFRESH_RATE–MAX_REFRESH_RATE: calling the data endpoint in a loop never reaches the external API more than once per period, failures included.

Simultaneous misses on the same key are coalesced: the first request calls fetch(), the others wait for its result (20 identical requests at the same instant → 1 upstream call, measured).

Each fetch() runs in a shared worker pool and is abandoned after FETCH_TIMEOUT; at most MAX_CONCURRENT_FETCHES run at once (abandoned ones count until they return), beyond that the call gets a 503 immediately. A cache hit costs about 20 µs, the worker hop about 50 µs.

Error contract

Inside fetch(), raise WidgetError(message, status=502) for expected failures; the message is shown to the user as is. Any other exception, a timeout or a non-JSON result becomes a 503 with a generic message, and the traceback goes to the widget_hub logger only.

{"error": {"code": "invalid_input", "message": "Invalid input.",
           "details": {"params": {"days": "Must be less than or equal to 16."}}}}

details only appears for invalid_input.

Using the adapters

All adapters expose the same routes, payloads and errors (they call widget_hub.api):

django-ninja (pip install "django-widget-hub[ninja]"):

from ninja import NinjaAPI
from widget_hub.contrib.ninja import build_router

api = NinjaAPI(auth=...)  # the router inherits your authenticators
api.add_router("/widgets", build_router())

DRF (pip install "django-widget-hub[drf]"):

from widget_hub.contrib.drf import build_router

urlpatterns = [path("api/widgets/", include(build_router().urls))]  # trailing_slash=False

Bodies are JSON parsed by widget_hub (not pydantic or serializers) so errors stay identical. Ninja and DRF answer with their own bodies when their authenticators reject a request.

The built-in front

{% load widget_hub %}
{% dashboard title="My dashboard" %}

The tag renders the logged-in user's dashboard through the session API in widget_hub.urls: a 12-column grid, drag to move (grip handle) or resize (corner), and the keyboard equivalent (focus the handle; arrow keys move, Shift + arrows resize, announced to screen readers). "Add widget" and the settings button open a form generated from the param schema (widgets grouped by service), with server errors next to each field and a password field for widgets using a credential. Each widget shows a loading placeholder, a subtitle summarising its params (to tell two RSS widgets apart) and "Updated 2 min ago"; it refreshes at its own rate and timers pause while the tab is hidden. A failing widget shows its error in its own frame, keeps its last data, retries at the next refresh and offers "Try again", without affecting the others. Placements that would overlap are refused; on small screens widgets stack in reading order. Touch targets grow to 44 px on touch devices and animations respect prefers-reduced-motion.

Data is rendered generically through textContent (objects as definition lists, arrays as lists, http(s) URLs as links or images). Custom rendering per widget:

WidgetHub.registerRenderer("weather.city_forecast", (element, data) => {
  element.textContent = `${data.temperature} °C`;
});

No secret is written in the page (only API URLs, refresh limits and Django's CSRF field). Themes follow prefers-color-scheme; force one with data-theme="light|dark" on .wh-dashboard or override the --wh-* CSS custom properties.

Security

Owner scoping. Every instance and credential operation takes the owner explicitly; another user's instance answers 404, exactly like a missing one.

CSRF. Unsafe requests must pass Django's CSRF check unless an API authenticator accepted the request and no session cookie was sent (token clients).

Validation before fetch(). Params are validated on create/update and again before every fetch(), so a changed declaration never feeds stale input to a widget.

SSRF: safe_fetch(). Use it whenever a URL comes from a user:

from widget_hub.security import safe_fetch

response = safe_fetch(params["feed"], timeout=5, max_bytes=1_000_000)
items = parse(response.text)  # .status, .headers, .content, .text, .json()

It accepts only http/https URLs without embedded credentials; resolves the host (within the deadline) and refuses it if any address is private, loopback, link-local (cloud metadata), CGNAT, multicast or reserved, including IPv4 embedded in IPv6 (mapped, NAT64, 6to4, Teredo); then connects to the address it checked, keeping the host name for Host, SNI and certificate checks, so DNS rebinding cannot swap the target. Redirects are followed by hand and re-validated, and the headers you pass are dropped as soon as a redirect changes scheme, host or port. The deadline is absolute (a watchdog closes the socket even if the server trickles bytes) and bodies are size-limited. Failures raise SafeFetchError, a WidgetError with a safe message (400 refused, 502 network error, 504 timeout).

Credentials. A widget that needs a user's token sets uses_credential = True (which requires cache_per_owner = True, enforced at startup) and reads context.credential: the owner's secret for that widget's service only, or None. Users store it with PUT credentials/{service} or in the front's settings form. Secrets are encrypted with Fernet under a key derived with HKDF-SHA256 from CREDENTIALS_KEY (or SECRET_KEY, with SECRET_KEY_FALLBACKS still decrypting after a rotation). They never appear in responses, repr(), logs or the admin.

Errors never include exception details (see the error contract).

The /about.json endpoint

include("widget_hub.urls") publishes a public GET /about.json in the Epitech Dashboard format, generated from the registry so it cannot disagree with the widgets that exist:

{"client": {"host": "10.0.0.7"},
 "server": {"current_time": 1760000000,
            "services": [{"name": "weather",
                          "widgets": [{"name": "city_forecast",
                                       "description": "Daily forecast for a city",
                                       "params": [{"name": "city", "type": "string"},
                                                  {"name": "days", "type": "integer"}]}]}]}}

client.host is REMOTE_ADDR unless ABOUT_TRUST_X_FORWARDED_FOR is set (do it only behind a reverse proxy that overwrites the header).

Architecture

flowchart LR
    subgraph Your project
        W["myapp/widgets.py<br/>@register Widget"]
        T["template<br/>{% dashboard %}"]
        N["NinjaAPI / DRF urls"]
    end
    W --> R[(registry)]
    R --> D["/about.json<br/>discovery"]
    T --> JS["dashboard.js"] --> V["session JSON API<br/>widget_hub.views"]
    N --> NA["contrib.ninja / contrib.drf"]
    V --> A["widget_hub.api<br/>owner · CSRF · permission · errors"]
    NA --> A
    A --> S["widget_hub.services<br/>validation · owner-scoped CRUD"]
    S --> M[(WidgetInstance<br/>Credential)]
    S --> F["fetching<br/>cache · timeout · concurrency cap"]
    F --> C[(Django cache)]
    F --> WF["Widget.fetch()"] --> SF["security.safe_fetch()"] --> X((external APIs))

Design decisions

Every non-obvious choice is written up as problem → options → choice → why → impact in docs/decisions.md. In short:

• params are an explicit list, not class attributes (order, no name clashes) — D4;
• duplicate names are startup errors — D5;
• one framework-agnostic service layer under thin adapters — D6, D11;
• shared cache by default, cache_per_owner opt-in, required for credentials — D7, D13;
• fetch() timeout via worker threads, capped — D8;
• one error contract, details only in logs — D9;
• safe_fetch() on the standard library with connection pinning — D12;
• a vanilla JS front with no build step — D14.

Real-world proof

The Epitech dashboard's widget layer (6 services, 8 widgets, commit e56b817) was migrated to the plugin in integration/epitech/: the hand-written registry, the widget routes and the WidgetInstance/ServiceCredential models were replaced, existing rows are moved by a tested data migration, and /about.json is byte-for-byte identical to the one captured from the original backend running, directly and behind the proxy.

The migration also improved the plugin: the React front stores pixel positions, which led to the POSITION_VALIDATOR setting. Full write-up, method and limits (the React front itself was not migrated): docs/migration-epitech.md.

Limitations and roadmap

• Timed-out fetch() calls cannot be killed (Python threads); they are capped and abandoned.
• Simultaneous misses are coalesced within one process only; several processes missing the same key at the same instant each call the upstream once.
• safe_fetch() is GET-only, without connection pooling or automatic decompression.
• The built-in front has no collision resolution (overlapping moves are refused, not reflowed) and renders data generically unless you register a renderer.
• Not yet: per-user rate limits beyond the refresh rate, async (async def fetch) widgets, translations of the front's strings.

Contributing

See CONTRIBUTING.md. Run pytest, node --test "tests/js/*.test.js" and ruff check . && ruff format --check . before opening a pull request. The changelog is in CHANGELOG.md.

Example project

example/ runs three widgets (example/demo_widgets/widgets.py): weather.current (public API), rss.latest (user URL through safe_fetch; try http://169.254.169.254/) and github.my_repositories (stored token).

pip install -e ".[dev]"
cd example && python manage.py migrate && python manage.py createsuperuser
python manage.py runserver      # log in at /admin/, then open /

License

MIT, see LICENSE.