millwork 0.1.0__py3-none-any.whl

millwork/manual/pages/app/auth.md

@@ -0,0 +1,188 @@
+---
+title: Signing in
+order: 2
+---
+
+# Signing in
+
+Without auth every page is open to anyone who reaches the server. With
+auth every page asks for a login first, a page is opened to anonymous
+visitors with `public=True`, and `s.user` says who is there. Identity comes
+from a provider; who gets in, and what the app keeps on them, is one
+function of the app's own.
+
+## Turning it on
+
+```python
+import datetime as dt
+
+import millwork as mw
+from millwork import auth, ui
+
+app = mw.App(
+    "projects",
+    secret=SECRET,
+    auth=auth.Auth(
+        [auth.AzureAD(tenant=TENANT, client_id=CLIENT_ID, client_secret=CLIENT_SECRET)],
+        on_login=admit,
+        session=dt.timedelta(hours=8),
+    ),
+)
+
+
+@app.page("/")
+def home(s: mw.Session) -> ui.Component:
+    return ui.Page(ui.Text(f"Hello, {s.user.name}."))
+
+
+@app.page("/privacy", public=True)
+def privacy(s: mw.Session) -> ui.Component:
+    return ui.Page(ui.Markdown(PRIVACY))
+```
+
+`secret` signs the session cookie and must be at least 32 characters;
+`millwork secret` prints one. Values such as the secret and the provider's
+credentials come from wherever the app keeps its secrets.
+
+The login page is part of millwork: the app's name, the theme's
+`login_image`, one button per OAuth provider, a username and password form
+when there is a password provider, and the message when a login was
+refused. A visitor who opens a gated page lands there and comes back to
+that page after signing in.
+
+## Providers
+
+`auth.AzureAD(tenant=, client_id=, client_secret=)` is Microsoft Entra ID,
+single tenant unless `single_tenant=False`. `auth.Google(client_id=,
+client_secret=)` is Google. Both are presets over `auth.OAuth(id, label=,
+authorize_url=, token_url=, userinfo_url=, client_id=, client_secret=,
+scopes=)`, which fits any OpenID Connect issuer. The provider's callback
+URL is `/_mw/auth/oauth/<id>/callback` on the app's origin.
+
+`auth.Password(verify)` takes a callable `(username, password) -> bool`,
+sync or async, and millwork runs it off the event loop. Hashes are
+scrypt from the standard library: `millwork hash-password --user ada`
+prints a line for a credentials file, and `auth.check_password(password,
+stored)` checks one against it.
+
+```python
+USERS = {"ada": "scrypt$..."}
+
+
+def verify(username: str, password: str) -> bool:
+    stored = USERS.get(username)
+    return stored is not None and auth.check_password(password, stored)
+```
+
+`auth.Dev(user)` signs every visitor in as that user; it is allowed with
+`--debug` and refused otherwise.
+
+Several providers can be listed together; the login page offers each.
+
+## Behind an authenticating proxy
+
+When a proxy in front of the app does the signing in (oauth2-proxy, a
+platform's built-in authentication, an access gateway), it names who it saw
+in request headers, and `auth.Headers` reads them. Give it the header names
+the proxy uses: `user` or `email` is required, `name`, `groups` and
+`picture` are optional, and `groups` is split on commas into
+`identity.raw["groups"]`. The person goes through `on_login` on every page
+load and socket connect, so keep that hook cheap; a sync hook runs off
+the event loop, and one that raises shows the error page and the tab
+stops retrying. A visitor the hook refuses sees the login page say so.
+`sign_out` is the proxy's own sign-out URL, which the user menu and
+`s.logout()` go to; without one the menu offers no sign-out, and
+`s.logout()` ends the person's sessions on this process, after which the
+proxy signs them in again on the next page. The proxy replaces these
+headers on the way through; a header that arrives twice is ignored.
+
+```python
+# oauth2-proxy in front of the app, with its default headers
+auth.Headers(
+    user="X-Forwarded-User",
+    email="X-Forwarded-Email",
+    name="X-Forwarded-Preferred-Username",
+    groups="X-Forwarded-Groups",
+    sign_out="/oauth2/sign_out",
+)
+```
+
+The headers are read when the app runs with `--proxied` or
+`App(proxied=True)`, as the Running chapter describes. A request that
+arrives without an identity lands on the login page, which says that
+sign-in happens before the app. The proxy's or platform's documentation
+lists the header names it sets and its sign-out URL.
+
+## Deciding who gets in
+
+After a provider has identified the visitor, `on_login(identity)` decides.
+`identity` carries `provider`, `subject`, `email` (lower-cased), `name`,
+`picture_url`, the provider's `raw` document and an `intent`. The hook
+returns a `User` to let the visitor in, or `None` to refuse with a message
+on the login page and a line in the log. It may be async and may look the
+person up somewhere.
+
+```python
+async def admit(identity: auth.Identity) -> auth.User | None:
+    if not identity.email or not identity.email.endswith("@example.com"):
+        return None
+    projects = await db.projects_of(identity.email)
+    if not projects:
+        return None
+    return auth.User(
+        id=identity.email,
+        name=identity.name or identity.email,
+        claims={"projects": [p.id for p in projects], "admin": identity.email in ADMINS},
+        picture_url=identity.picture_url,
+    )
+```
+
+A `User` is `id`, `name`, `claims` and `picture_url`. `claims` is the
+app's own dictionary, capped at 2 KB: roles, the projects a person may
+see, flags. A picture is a URL. Without `on_login` every
+identified visitor becomes a `User` with the e-mail as `id`, and a provider
+that gives no e-mail is refused.
+
+`Auth(intents={"demo": "Try the demo"})` adds a secondary button to the
+login page for each intent; the one pressed arrives as `identity.intent`,
+and the hook decides what it means.
+
+## In a page
+
+`s.user` is the `User`, or `None` on a public page when nobody is signed
+in. Authorisation is the app's: read `s.user.claims` in `connect` and raise
+`mw.Forbidden(message)` when this page or this project is not for this
+person. The Pages chapter shows the hook.
+
+```python live
+def example(s):
+    who = f"{s.user.name} ({s.user.id})" if s.user else "nobody; the manual runs without auth"
+    return ui.Text(f"Signed in as {who}.", variant="muted")
+```
+
+The `ui.Header` shows the signed-in person's picture or initials with a
+menu that holds the theme choice and sign-out; `user_menu=False` hides it.
+`s.logout()` signs out from a handler: the cookie is cleared, the person's
+other sessions on this process end with a note in their tabs, and the tab
+goes to the login page.
+
+## The session cookie
+
+The cookie is a signed token holding the `User`, `HttpOnly`, `SameSite=Lax`,
+`Secure` over HTTPS, with a fixed lifetime set by `session` (seven days by
+default). Its name and path carry the app's prefix, `mw_auth_sales` under
+`/sales`, so apps side by side on one host each read their own, and it is
+signed for the app by name, so apps that share a secret still keep their
+sign-ins apart. After that long a person signs in again. The cookie holds
+the `User` and is valid on any replica with the same secret. Signing out
+clears the browser's cookie and ends the person's sessions on that
+process; a copy of the cookie stays valid until it expires, so the
+lifetime is the bound, and an app with sensitive data sets `session` to a
+working day. The socket is bound to the cookie, so a session is resumed
+by its own user. Logins and refusals are logged with the identifier;
+`log_identity="hashed"` logs a hash instead.
+
+Identity is what the provider says and the record is what `on_login`
+returns; `claims` is a dictionary the app reads. An access token the app
+needs for its own API calls is obtained in `on_login` and kept by the
+app.

millwork/manual/pages/app/pages.md

@@ -0,0 +1,200 @@
+---
+title: Pages and routing
+order: 0
+---
+
+# Pages and routing
+
+An app is a `mw.App` with pages on it. A page is a path and a function of
+the session that returns the component tree for that path. The browser
+opens the path, the tab connects a socket, and from then on Python renders
+and handles events over that socket. There is one session per tab.
+
+## An app and its pages
+
+```python
+import millwork as mw
+from millwork import ui
+
+app = mw.App("projects")
+
+
+@app.page("/", title="Projects")
+def home(s: mw.Session) -> ui.Component:
+    return ui.Page(ui.Text("All projects"), title="Projects")
+
+
+@app.page("/about")
+def about(s: mw.Session) -> ui.Component:
+    return ui.Page(ui.Text("About this app"))
+```
+
+`title` is the browser tab's title; without one the app's name is used.
+Paths match in the order the pages are registered, and a path no page
+matches is a 404.
+
+`millwork run app.py` serves the file's `app`; `millwork run package.module:app`
+names the object. `--port` picks the port, `--reload` restarts the process
+when a Python file changes, `--debug` shows page errors in the tab and
+watches the theme file and the custom components for changes. Under
+uvicorn or another ASGI server, `app.asgi` is the application.
+
+## Parameters in the path
+
+A path can carry parameters in Starlette's syntax. `{name}` takes one
+segment as a string; `{name:int}`, `{name:float}` and `{name:uuid}` convert
+it, and a path that does not convert does not match. `{name:path}` takes
+the rest of the path. The values arrive in `s.params`, and `s.path` is the
+path as opened.
+
+```python
+@app.page("/projects/{project_id:int}")
+def project(s: mw.Session) -> ui.Component:
+    return ui.Page(ui.Text(f"Project {s.params['project_id']}"))
+```
+
+## Moving between pages
+
+A `ui.Link` whose `href` is a path inside the app navigates over the
+session: no reload, the tab's history gets an entry, the back button
+works. From a handler, `s.navigate(path)` does the same. A `#heading` on
+the path scrolls to that heading once the page is up, which is how this
+manual's search opens a section.
+
+```python live
+def example(s):
+    return ui.Row(
+        ui.Button("Open the Charts chapter", on_click=lambda s, _: s.navigate("/components/charts")),
+        ui.Link(label="or follow a link", href="/components/charts#stat"),
+        ui.Text(f"You are at {s.path}", variant="muted"),
+        gap=4,
+    )
+```
+
+A link to another site is an ordinary link; give it `target="_blank"` to
+open a new tab.
+
+## When a page is missing
+
+A path no page matches lands on the app's not-found page: over HTTP as a
+404 that serves the shell, and over the session when a link or
+`s.navigate` asks for it, so the tab keeps its session and can go on from
+there. `connect` reaches the same pages by raising: `mw.NotFound(message)`
+when what the path names does not exist, `mw.Forbidden(message)` when this
+person may not open it. The session lands on the error page under the path
+that was asked for, with the message if one was given.
+
+Without any app code the framework's own pages are shown: the theme's
+logo, a title and a line from the string table, and a way home, in the
+same frame as the login page. An app replaces them with pages of its own,
+written like any other page: `s.params["path"]` is the path asked for and
+`s.params["message"]` what `connect` raised with, or empty.
+
+```python
+@app.not_found
+def missing(s):
+    return ui.Page(
+        ui.Stack(
+            ui.Logo(cls="h-9 self-start"),
+            ui.Text("Nothing here", variant="title"),
+            ui.Text(s.params["message"] or f"There is no page at {s.params['path']}.", variant="muted"),
+            ui.Input(kind="search", placeholder="Search instead", on_submit=search),
+            gap=3,
+            cls="max-w-sm",
+        ),
+    )
+
+
+@app.forbidden(title="Private")
+def private(s):
+    return ui.Page(ui.Text(s.params["message"] or "Ask the owner for access."))
+```
+
+`ui.Logo` is the theme's logo, light or dark with the scheme, for a page
+outside the app bar. The link below goes to a page this manual does not
+have, which is the framework's own not-found page in this manual's theme.
+
+```python live
+ui.Row(
+    ui.Logo(cls="h-6"),
+    ui.Link(label="Open a page that does not exist", href="/components/nothing-here"),
+    gap=4,
+)
+```
+
+A failure before the bundle can run, a crash in an app's own route or the
+bundle missing, is a plain HTML page with the same title and text, in the
+theme's colours and font; the traceback goes to the log. In debug mode a
+crash shows Starlette's own traceback page.
+
+## State and the session
+
+A page's state is a Pydantic model named on the page, or on the app as the
+default for every page. `s.state` is an instance of it, made new when the
+page is opened and again on every navigation to a page. The session itself
+outlives the page: its files, its identity and its tasks stay while the tab
+moves around the app.
+
+```python
+class State(BaseModel):
+    selected: list[int] = []
+
+
+@app.page("/projects/{project_id:int}", state=State)
+def project(s: mw.Session[State]) -> ui.Component:
+    ...
+```
+
+Everything a page shows comes from `s.state` and from what its handlers put
+there, so a page is a plain function and handlers are where things
+change.
+
+## Connect and close
+
+A page can have a `connect` hook, run once each time the page is opened,
+before the first render, with the path parameters as keyword arguments. It
+may be async, and it is where a page loads what it needs, starts a task,
+or decides that the visitor may not be here. `mw.NotFound()` and
+`mw.Forbidden(message)` raised from it keep the tab on the page it came
+from and show the message; a page opened directly shows the message and
+stops there.
+
+```python
+@project.connect
+async def load(s: mw.Session[State], project_id: int) -> None:
+    project = await db.project(project_id)
+    if project is None:
+        raise mw.NotFound()
+    if s.user and s.user.id not in project.members:
+        raise mw.Forbidden("Not your project.")
+    s.state.project = project
+    s.task(refresh_documents(s))
+
+
+@project.close
+async def leave(s: mw.Session[State]) -> None:
+    await db.release(s.state.project.id)
+```
+
+The `close` hook runs once, with the state still intact, when the session
+ends: the tab said goodbye, or it has been gone longer than the grace
+period. `App(session_grace=300)` sets that period in seconds; a tab that
+reconnects within it, after a sleep or a dropped network, gets its session
+back with everything in it.
+
+## Navigation in the frame
+
+`ui.Header(links=[...])` puts links in the app bar and `ui.Sidebar` holds
+a longer list. This manual's sidebar is a `Sidebar` of `Link`s with the
+current page drawn as text instead; the Layout chapter shows both.
+
+## Beyond pages
+
+`App` is a Starlette application, and an app adds to it through Starlette:
+`app.route(path, endpoint, methods=[...])` for an API endpoint,
+`app.mount(path, asgi_app)` for anything ASGI, FastAPI included,
+`app.middleware(cls)` for pure ASGI middleware, and `app.on_startup` and
+`app.on_shutdown` for hooks around the process. The `public/` folder next
+to the app is served at `/public/`. Everything millwork owns lives under
+`/_mw/`, leaving every other path to the app; `/_mw/health` answers 200
+once the startup hooks are done.

millwork/manual/pages/app/running.md

@@ -0,0 +1,242 @@
+---
+title: Running
+order: 5
+---
+
+# Running
+
+One process serves an app: Python with the built bundle inside the
+package. What the app needs is said on the `App`, in Python, with values
+from wherever the app keeps its secrets. `millwork run` starts the
+process, and a handful of flags cover a reverse proxy, a unix socket and
+a path prefix.
+
+## The App's options
+
+```python
+app = mw.App(
+    "projects",
+    state=State,                      # the default state model for every page
+    public="public",                  # served at /public/; None for no static folder
+    components="components",          # custom components, .jsx files; None for none
+    theme="themes/dark.json",         # a path or a Theme; public/theme.json is found on its own
+    secret=SECRET,                    # signs cookies; 32 characters or more, required with auth
+    auth=...,                         # see Signing in
+    origins=["https://projects.example.com"],
+    session_grace=300,                # seconds a session waits for its tab to come back
+    max_sessions_per_client=20,       # live sessions per user, or per address without auth
+    max_sessions=1000,                # live sessions in the process
+    files=mw.Files("/var/lib/projects/files", max_session_mb=200, max_total_mb=2000),
+    threads=8,                        # the pool sync tasks and handlers run in
+    keep_alive=False,
+    proxied=False,                    # True behind a reverse proxy; see Serving
+)
+```
+
+- `origins` is the allow-list for the socket and the login route; the
+  default is the app's own origin.
+- `files` is where uploads and generated files live while a session
+  lives, with a quota per session and one for the process. The folder is
+  private to the process's user, and directories left by old sessions are
+  swept. The default is the system's temporary directory, which on some
+  hosts is memory, so a deployment names a disk.
+- `session_grace` is how long a session waits for its tab to come back
+  after the socket drops, with its state intact.
+- `max_sessions_per_client` and `max_sessions` count live sessions,
+  those in grace included. Over the client's cap, that client's session
+  longest without a tab makes room; over the process cap, anyone's. A
+  new session is refused when every one still has a tab. A session ended
+  that way, or by a sign-out in another tab, tells its tab so: the page
+  stays readable, takes no more input, and offers a reload.
+- `threads` sizes the pool that runs sync tasks; the default is Python's.
+- `keep_alive=True` makes every open tab fetch the health route every
+  thirty seconds, for a host that stops an idle process; by default a tab
+  does so while a task or a reply runs.
+- `proxied=True` says a reverse proxy is in front; the Serving section
+  below.
+
+The settings this manual runs with:
+
+```python live
+def example(s):
+    app = s.app
+    return ui.Table(
+        rows=[
+            {"option": "name", "value": app.name},
+            {"option": "session_grace", "value": f"{app.session_grace:.0f} s"},
+            {"option": "max_sessions_per_client", "value": app.max_sessions_per_client},
+            {"option": "max_sessions", "value": app.max_sessions},
+            {"option": "files", "value": f"{app.files.max_session_mb} MB per session, {app.files.max_total_mb} MB in all"},
+            {"option": "origins", "value": ", ".join(app.origins) or "same origin"},
+            {"option": "threads", "value": app.threads or "Python's default"},
+            {"option": "keep_alive", "value": app.keep_alive},
+            {"option": "proxied", "value": app.proxied},
+            {"option": "debug", "value": app.debug},
+            {"option": "auth", "value": "on" if app.auth else "off"},
+        ],
+        row_key="option",
+        height=400,
+    )
+```
+
+## Development
+
+`millwork run app.py --reload --debug` is the loop. `--reload` restarts
+the process when a Python file changes; the tab shows "Reconnecting" and
+remounts when the server is back. `--debug` shows page errors in the
+tab, turns the framework's warnings into toasts, pushes a changed theme
+file or custom component to every open tab, and allows the `Dev` auth
+provider. Tests drive a session without a browser, so for most changes
+the loop is edit, run pytest, and the browser is for looking.
+
+## Serving
+
+In production one process serves one app behind a reverse proxy that
+ends TLS and passes the websocket upgrade through:
+
+```
+uv run millwork run app.py --host 127.0.0.1 --port 8000 --proxied
+```
+
+`--proxied`, or `App(proxied=True)`, says a reverse proxy is in front.
+The app then takes the visitor's address and scheme from the proxy's
+`X-Forwarded-For` and `X-Forwarded-Proto`, and the visitor's identity from
+the headers an `auth.Headers` provider names. Anyone who can reach the
+process can send those headers too, so a proxied app listens where only
+its proxy connects: a unix socket, a loopback port, or a container
+network.
+
+`/_mw/health` answers 200 once the startup hooks have run and 503 before
+that and during shutdown, for a host that waits for readiness. The
+process exits cleanly on SIGTERM: sessions get their `close` hook, tasks
+are cancelled, uploads in flight are cut. Logs go to standard error.
+
+`app.asgi` is the ASGI application itself, for a server of your own
+choosing; under uvicorn directly, pass `--no-proxy-headers`, since
+millwork applies the forwarded headers, and `--ws-max-size 1048576`, the
+bound `millwork run` puts on a message from the tab (uploads travel in
+smaller frames).
+
+## A unix socket
+
+On one machine with the proxy, `--uds` listens on a unix socket. The
+socket is created with mode 0660, whatever the umask, so the proxy
+connects when it runs in the app's group. A socket is reached through a
+proxy, so `--uds` implies `--proxied`.
+
+```
+uv run millwork run app.py --uds /run/sales/app.sock
+```
+
+```nginx
+location / {
+    proxy_pass http://unix:/run/sales/app.sock:/;
+    proxy_http_version 1.1;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection "upgrade";
+    proxy_set_header Host $host;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+}
+```
+
+Like a port, the path is refused while another process answers on it. A
+socket file nobody answers on is replaced at the next start, and anything
+else at the path stops the start. The health route is reached the same
+way: `curl --unix-socket /run/sales/app.sock http://app/_mw/health`.
+
+## Under a path prefix
+
+An app can live under a path on a shared host, `https://apps.example/sales/`,
+next to other apps. The proxy strips the prefix and the server is told it:
+
+```
+uv run millwork run app.py --port 8000 --root-path /sales --proxied
+```
+
+```nginx
+location /sales/ {
+    proxy_pass http://127.0.0.1:8000/;
+    proxy_http_version 1.1;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection "upgrade";
+    proxy_set_header Host $host;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+}
+```
+
+Every URL the server writes into the page is under the prefix, and the
+cookies carry it in name and path, so apps side by side on one host each
+have their own. Inside the app everything is an app path: page paths,
+`ui.Link` targets, `s.navigate`, an image's `src`, a path in Markdown;
+the tab puts each one under the prefix as it renders it. A custom
+component that builds a URL itself reads the prefix from
+`window.__mw.base`, which is empty at the root. The manual takes the flag
+too: `millwork docs --root-path /manual`.
+
+## What a host needs
+
+Any host that runs one process and routes HTTPS to it serves a millwork
+app. It provides:
+
+- TLS at the proxy or the platform's edge, with the websocket upgrade
+  passed through.
+- `--proxied`, and a listener only the proxy can reach: a unix socket, a
+  loopback port, or the container's network.
+- `/_mw/health` as the readiness probe: 200 once the startup hooks have
+  run, 503 before that and during shutdown. As a liveness probe it would
+  restart a slow start, so that one gets a generous threshold.
+- A files directory with room, named with `Files(...)`, when uploads are
+  larger than the temporary directory should hold.
+- The `secret` and the provider's credentials from the environment or the
+  platform's secret store.
+- `keep_alive=True` when the host stops an idle container, since
+  platforms differ on whether an open websocket counts as activity and
+  the health pings count everywhere.
+- A path prefix per app, or a hostname per app, when several share a
+  host.
+
+The millwork parts of a service definition are the command line. Under
+systemd, with the socket in the unit's runtime directory and the files in
+its state directory:
+
+```ini
+RuntimeDirectory=millwork
+StateDirectory=millwork/sales
+ExecStart=/srv/apps/sales/.venv/bin/millwork run app.py --uds /run/millwork/sales.sock --root-path /sales
+```
+
+In a container, behind the platform's router:
+
+```dockerfile
+CMD ["/app/.venv/bin/millwork", "run", "app.py", "--host", "0.0.0.0", "--port", "8000", "--proxied"]
+```
+
+## More than one replica
+
+HTTP is stateless and the socket is the session: identity comes from the
+cookie, and everything a session owns, its state, its files, its tasks,
+travels over the socket to the process that holds it. Replicas need no
+sticky routing and no shared storage. When a replica goes away, its
+sessions go with it, and their tabs start fresh sessions elsewhere, as
+they would on a reload. The cookie is valid on every replica that has the
+same `secret`.
+
+## The page's security headers
+
+Every page carries a Content Security Policy: scripts from the app's
+origin with a nonce, connections to the app's origin, images and media
+from anywhere over HTTPS, and no framing by other sites. An app with a
+`components/` folder also allows `eval`, since custom components are
+compiled in the tab. A custom component that needs a library loads it
+from `public/`, as the Charts chapter shows. `App(csp=None)` drops the
+header, and a string of your own replaces it; `{scripts}` in it is where
+millwork puts the script sources.
+
+## Hooks around the process
+
+`app.on_startup` and `app.on_shutdown` register functions, sync or async,
+that run once around the process: warm a cache, open and close a pool.
+`app.route`, `app.mount` and `app.middleware` add to the Starlette
+application, as the Pages chapter shows.