diff --git a/docs/caching.md b/docs/caching.md index 4323909..e95a491 100644 --- a/docs/caching.md +++ b/docs/caching.md @@ -9,6 +9,7 @@ When you want the instant feel of Outlook and Teams on the web, add caching on t |---|---|---| | A cache that just works | `SQLiteCache` | one SQLite file | | Your own storage (Redis, Postgres, a queue, memory) | `note.stream()` | one cursor string per kind | +| A web app or API, using normal calls only | [frontend-and-api.md](frontend-and-api.md) | short-lived results | `SQLiteCache` is built on `stream()`, so both behave the same. diff --git a/docs/frontend-and-api.md b/docs/frontend-and-api.md new file mode 100644 index 0000000..0f1e0fd --- /dev/null +++ b/docs/frontend-and-api.md @@ -0,0 +1,639 @@ +# A native-feeling app on top of OutNote + +This page shows how to make a web app feel like Outlook or Teams when OutNote runs behind your own API. +It uses only normal calls like `emails()` and `chats()`, not `stream()` or `SQLiteCache`, so the same +ideas work with any backend. + +The API layer is shown twice, so pick one: + +- **[With `outnote.api`](#with-outnoteapi):** import the cache and client handling, and write only your routes. +- **[Without `outnote.api`](#without-outnoteapi):** own all the code, for example to change how it works or + to port it to another language. + +Both behave the same and passed the same tests, and [the frontend](#the-frontend) works with either. + +``` +Browser (IndexedDB) -> Your API (short-lived cache) -> OutNote -> Microsoft +``` + +The two layers do different jobs, and you can use either one alone: + +| Layer | What it does | What the user feels | +|---|---|---| +| Browser cache | Draws saved data immediately, then checks for updates | The app opens instantly, even on a slow connection | +| API cache | Shares results, merges duplicate requests, answers quickly | Fewer waits and fewer Microsoft rate limits | + +The code below is a working example with FastAPI and plain JavaScript. It ran against a local API with +fake data in a real browser, and token rotation was tested on a real account. The complete app hasn't run +against Microsoft or with real users. Authentication, token storage and your UI are placeholders that you +need to fill in. + +## What makes it feel native + +These come from watching the traffic of Outlook and Teams on the web: + +1. **Draw first, then fetch.** Show saved data straight away and update it quietly when the answer arrives. +2. **One startup request.** Outlook's `startupdata.ashx` returns config, folders and the first 25 + conversations together. Your `/api/bootstrap` can do the same. +3. **Small lists, details on demand.** `emails()` returns list fields, about 8x faster than every field. + Fetch the full message with `email(id)` when it's needed. +4. **Load ahead, gently.** Outlook fetches conversation details in the background, about 130 ms apart, + well after the first screen. +5. **Apply actions immediately.** Show the change first, and undo it if the server refuses. +6. **Keep the app itself offline.** Both web apps use a service worker, so the page opens without waiting + for the network. + +## The API layer + +### How the cache works + +Both versions decide what to do by how old a result is: + +| Age of the result | What happens | +|---|---| +| Under `fresh` seconds | Answers from memory | +| Under `stale` seconds | Answers from memory, and refreshes in the background | +| Older, or nothing saved | Waits for Microsoft. If that fails and something old exists, returns that | + +Identical requests share one Microsoft call, and a slow old read can't overwrite a newer write. + +### With `outnote.api` + +`outnote.api` is an optional module with what an API needs. It uses only the standard library and works +with any framework. Nothing changes for the rest of OutNote unless you import it. + +`load_token`, `save_token` and `current_user` are yours to write. **`current_user` must come from your own +authentication**, because the cache trusts it to keep users' data apart. + +`ClientPool` keeps one client per user, and calls `save_token` whenever a refresh token rotates. Save it, or +the user may eventually have to sign in again. + +```python +# api.py +from concurrent.futures import ThreadPoolExecutor + +from fastapi import Depends, FastAPI, HTTPException, Request, Response +from outnote import GraphError +from outnote.api import ApiCache, ClientPool, error_response, respond + +app = FastAPI() +cache = ApiCache(fresh=30, stale=600) +_startup = ThreadPoolExecutor(8) + + +def current_user(request: Request) -> str: + """Your authentication: return a stable id for the signed-in user, or raise 401.""" + raise HTTPException(401) + + +def load_token(user: str) -> str: + """Your storage: return this user's refresh token. Keep it encrypted, like a password.""" + raise NotImplementedError + + +def save_token(user: str, token: str) -> None: + """Your storage: replace this user's refresh token with the rotated one.""" + raise NotImplementedError + + +clients = ClientPool(load_token, save_token) + + +def reply(request: Request, entry) -> Response: + status, headers, body = respond(entry, request.headers.get("if-none-match")) + return Response(body, status, headers) + + +@app.exception_handler(GraphError) +def graph_error(request: Request, error: GraphError): + """Tell the browser how long Microsoft asked to wait instead of hiding it.""" + status, headers, body = error_response(error) + return Response(body, status, headers) + + +@app.get("/api/bootstrap") +def bootstrap(request: Request, user: str = Depends(current_user)): + """Everything the first screen needs, in one request.""" + client = clients.get(user) + + def load(): + mail = _startup.submit(lambda: cache.get(user, "mail", lambda: client.emails(top=25)).data) + chats = _startup.submit(lambda: cache.get(user, "chats", lambda: client.chats(25)).data) + return {"mail": mail.result(), "chats": chats.result()} + + return reply(request, cache.get(user, "bootstrap", load, fresh=5)) + + +@app.get("/api/mail") +def mail(request: Request, user: str = Depends(current_user)): + client = clients.get(user) + return reply(request, cache.get(user, "mail", lambda: client.emails(top=25))) + + +@app.get("/api/mail/{message_id}") +def message(message_id: str, request: Request, user: str = Depends(current_user)): + client = clients.get(user) + fetch = lambda: client.email(message_id) # noqa: E731 + return reply(request, cache.get(user, f"mail/{message_id}", fetch, fresh=300, stale=3600)) + + +@app.post("/api/mail/{message_id}/read") +def mark_read(message_id: str, user: str = Depends(current_user)): + clients.get(user).mark_read(message_id) + # Writes always go to Microsoft, then every result they could have changed is forgotten. + cache.invalidate(user, "mail") + cache.invalidate(user, "bootstrap") + return {"ok": True} + + +@app.post("/api/sign-out") +def sign_out(user: str = Depends(current_user)): + cache.invalidate(user) + clients.drop(user) + # Also delete the stored refresh token here, and end your own session. + return {"ok": True} +``` + +### Without `outnote.api` + +This version uses only OutNote's normal client, and you own every line. It has two files. + +First the cache, which needs only the standard library: + +```python +# api_cache.py +import hashlib +import json +import logging +import threading +import time +from collections import OrderedDict +from concurrent.futures import ThreadPoolExecutor +from dataclasses import dataclass +from typing import Any + +log = logging.getLogger("api_cache") + + +@dataclass +class Entry: + """One cached result: the data, its JSON `body`, an `etag`, and how old it is.""" + + body: bytes + etag: str + at: float + data: Any + + @property + def age(self): + return time.monotonic() - self.at + + +class ApiCache: + """A per-user, in-memory cache of results. Safe to share between threads. + + Up to `fresh` seconds old, a result is answered from memory. Up to `stale` seconds, it's answered + from memory and refreshed in the background. Older than that, the caller waits for a new one, and + gets the old one only if the refresh fails. Identical requests share one fetch. + + It holds real mail and chats in memory, keyed by the `user` you pass, so that value must come from + your own authentication. For several servers, keep this logic but store entries somewhere shared.""" + + def __init__(self, fresh=30, stale=600, max_entries=5000, workers=8): + self.fresh, self.stale, self.max_entries = fresh, stale, max_entries + self._entries: OrderedDict = OrderedDict() + self._running: dict = {} # key -> Future, so identical requests share one fetch + self._generation: dict = {} # user -> counter, so a slow old fetch can't overwrite a write + self._lock = threading.RLock() + self._pool = ThreadPoolExecutor(workers, thread_name_prefix="api-cache") + + def get(self, user, name, fetch, fresh=None, stale=None): + """The `Entry` for this user's `name`, calling `fetch()` if needed. `fetch` must return + JSON-serializable data. Raises whatever `fetch` raises if there's nothing old to fall back on.""" + fresh = self.fresh if fresh is None else fresh + stale = self.stale if stale is None else stale + key = (user, name) + with self._lock: + entry = self._entries.get(key) + if entry and entry.age < fresh: + self._entries.move_to_end(key) + return entry + future = self._refresh(key, fetch) + if entry and entry.age < stale: + return entry # the refresh carries on in the background + try: + return future.result() + except Exception: + if entry: # something old beats an error + log.warning("serving old data for %s after a failed refresh", name, exc_info=True) + return entry + raise + + def invalidate(self, user, prefix=""): + """Forget this user's results whose name starts with `prefix`. Call it after every write that + could change them, and with no prefix when the user signs out.""" + with self._lock: + self._generation[user] = self._generation.get(user, 0) + 1 + for key in [k for k in self._entries if k[0] == user and k[1].startswith(prefix)]: + del self._entries[key] + for key in [k for k in self._running if k[0] == user]: + del self._running[key] + + def close(self): + """Stop the background threads, for a clean shutdown.""" + self._pool.shutdown(wait=False, cancel_futures=True) + + def _refresh(self, key, fetch): + future = self._running.get(key) + if not future: + generation = self._generation.get(key[0], 0) + future = self._pool.submit(self._load, key, fetch, generation) + self._running[key] = future + return future + + def _load(self, key, fetch, generation): + try: + data = fetch() + body = json.dumps(data, separators=(",", ":")).encode() + etag = '"' + hashlib.sha256(body).hexdigest()[:32] + '"' + entry = Entry(body, etag, time.monotonic(), data) + with self._lock: + if self._generation.get(key[0], 0) == generation: + self._entries[key] = entry + self._entries.move_to_end(key) + while len(self._entries) > self.max_entries: + self._entries.popitem(last=False) + return entry + finally: + with self._lock: + if self._generation.get(key[0], 0) == generation: # a newer fetch keeps its place + self._running.pop(key, None) +``` + +Then the routes. Again, `load_token`, `save_token` and `current_user` are yours to write, and **`current_user` +must come from your own authentication**. Unlike `ClientPool`, `client_for` here has no limit on how many +clients it keeps, so add one if you serve many users from one process. + +```python +# api_plain.py +import json +import threading +from concurrent.futures import ThreadPoolExecutor + +from entrance import Broker +from fastapi import Depends, FastAPI, HTTPException, Request, Response +from outnote import GraphError, OutNote + +from api_cache import ApiCache + +app = FastAPI() +cache = ApiCache(fresh=30, stale=600) +_startup = ThreadPoolExecutor(8) +_clients, _clients_lock = {}, threading.Lock() + + +def current_user(request: Request) -> str: + """Your authentication: return a stable id for the signed-in user, or raise 401.""" + raise HTTPException(401) + + +def load_token(user: str) -> str: + """Your storage: return this user's refresh token. Keep it encrypted, like a password.""" + raise NotImplementedError + + +def save_token(user: str, token: str) -> None: + """Your storage: replace this user's refresh token with the rotated one.""" + raise NotImplementedError + + +def client_for(user: str) -> OutNote: + """One client per user, because it keeps that user's access tokens in memory. Token requests run + one at a time per user, and a rotated refresh token is saved as soon as it appears.""" + with _clients_lock: + if user in _clients: + return _clients[user] + broker = Broker(load_token(user)) + lock = threading.Lock() + + def token(client_id, *scope): + with lock: + before = broker.refresh_token + access = broker(client_id, *scope) + if broker.refresh_token != before: + save_token(user, broker.refresh_token) + return access + + _clients[user] = OutNote(token) + return _clients[user] + + +def reply(request: Request, entry) -> Response: + headers = {"ETag": entry.etag, "Cache-Control": "private, no-cache", "Age": str(int(entry.age))} + if request.headers.get("if-none-match") == entry.etag: + return Response(status_code=304, headers=headers) + return Response(entry.body, media_type="application/json", headers=headers) + + +@app.exception_handler(GraphError) +def graph_error(request: Request, error: GraphError): + """Tell the browser how long Microsoft asked to wait instead of hiding it.""" + status = error.status if error.status in (403, 404, 429) else 502 + headers = {"Retry-After": str(int(error.retry_after))} if error.retry_after else {} + return Response(json.dumps({"error": str(error)}), status, headers, "application/json") + + +@app.get("/api/bootstrap") +def bootstrap(request: Request, user: str = Depends(current_user)): + """Everything the first screen needs, in one request.""" + client = client_for(user) + + def load(): + mail = _startup.submit(lambda: cache.get(user, "mail", lambda: client.emails(top=25)).data) + chats = _startup.submit(lambda: cache.get(user, "chats", lambda: client.chats(25)).data) + return {"mail": mail.result(), "chats": chats.result()} + + return reply(request, cache.get(user, "bootstrap", load, fresh=5)) + + +@app.get("/api/mail") +def mail(request: Request, user: str = Depends(current_user)): + client = client_for(user) + return reply(request, cache.get(user, "mail", lambda: client.emails(top=25))) + + +@app.get("/api/mail/{message_id}") +def message(message_id: str, request: Request, user: str = Depends(current_user)): + client = client_for(user) + fetch = lambda: client.email(message_id) # noqa: E731 + return reply(request, cache.get(user, f"mail/{message_id}", fetch, fresh=300, stale=3600)) + + +@app.post("/api/mail/{message_id}/read") +def mark_read(message_id: str, user: str = Depends(current_user)): + client_for(user).mark_read(message_id) + # Writes always go to Microsoft, then every result they could have changed is forgotten. + cache.invalidate(user, "mail") + cache.invalidate(user, "bootstrap") + return {"ok": True} + + +@app.post("/api/sign-out") +def sign_out(user: str = Depends(current_user)): + cache.invalidate(user) + with _clients_lock: + _clients.pop(user, None) + # Also delete the stored refresh token here, and end your own session. + return {"ok": True} +``` + +### Rules for the API layer + +These apply to both versions. + +- **Key every result by user.** Never cache by URL alone, or one person can receive another's mail. +- **Send `Cache-Control: private`.** Shared proxies and CDNs must never store these responses. +- **Never log response bodies or tokens,** and keep your API on HTTPS. +- **Write straight through.** Don't cache writes, and invalidate what they change. +- **Rate limit per user.** Your users may share Microsoft's limits for these client ids, so one busy user + can slow everyone down. +- **Several API servers need a shared cache.** `ApiCache` lives in one process's memory. With more than + one server, or across restarts, keep the same logic but store entries in something like Redis, encrypted. +- **Clear on sign-out.** Call `cache.invalidate(user)` and `clients.drop(user)`, and delete the stored + refresh token. +- **Treat the cache as sensitive.** It holds real mail and chats, so keep the times short. + +Microsoft can take a moment to show a change you just made, so a read right after a write may still +return the old value. The frontend's immediate update covers that gap. + +## The frontend + +### Draw first, then update + +`swr.js` stores responses in IndexedDB and asks your API whether they changed. If they didn't, the API +answers `304`, with no body and no redraw. + +```javascript +// swr.js +let dbPromise; + +/** Call once after sign-in. One database per user, so accounts never mix. */ +export function openCache(userId) { + dbPromise = new Promise((resolve, reject) => { + const open = indexedDB.open(`app-cache-${userId}`, 1); + open.onupgradeneeded = () => open.result.createObjectStore("responses"); + open.onsuccess = () => resolve(open.result); + open.onerror = () => reject(open.error); + }); + return dbPromise; +} + +/** Call on sign-out. Close the app's other tabs first, or the delete waits for them. */ +export async function clearCache(userId) { + (await dbPromise)?.close(); + dbPromise = undefined; + await new Promise((resolve) => { + const del = indexedDB.deleteDatabase(`app-cache-${userId}`); + del.onsuccess = del.onerror = del.onblocked = () => resolve(); + }); +} + +async function store(mode, action) { + const db = await dbPromise; + return new Promise((resolve, reject) => { + const request = action(db.transaction("responses", mode).objectStore("responses")); + request.onsuccess = () => resolve(request.result); + request.onerror = () => reject(request.error); + }); +} + +export const readCache = (url) => store("readonly", (s) => s.get(url)); +export const writeCache = (url, value) => store("readwrite", (s) => s.put(value, url)); + +/** + * Draws saved data straight away, then updates it if the API has something newer. + * `render(data, { stale })` can run twice. `stale` is true while the data is unconfirmed. + * Resolves to the newest data, or the saved data if the network failed. + */ +export async function swr(url, render, { onError } = {}) { + const saved = await readCache(url); + if (saved) render(saved.data, { stale: true }); + try { + const response = await fetch(url, { + cache: "no-store", // so this code sees the 304 itself + headers: saved?.etag ? { "If-None-Match": saved.etag } : {}, + }); + if (response.status === 304) { + render(saved.data, { stale: false }); + return saved.data; + } + if (!response.ok) { + const error = new Error(`${url}: ${response.status}`); + error.status = response.status; + error.retryAfter = Number(response.headers.get("Retry-After")) || null; + throw error; + } + const data = await response.json(); + await writeCache(url, { data, etag: response.headers.get("ETag") }); + render(data, { stale: false }); + return data; + } catch (error) { + onError?.(error, Boolean(saved)); + if (!saved) throw error; + return saved.data; + } +} + +/** Loads details ahead of time, one at a time, like Outlook. Skips anything already saved. */ +export async function prefetch(urls, { gapMs = 130 } = {}) { + if (navigator.connection?.saveData) return; + for (const url of urls) { + if (document.hidden) return; + if (await readCache(url)) continue; + try { + const response = await fetch(url, { cache: "no-store" }); + if (!response.ok) return; // a 429 or an error: stop and try another time + await writeCache(url, { data: await response.json(), etag: response.headers.get("ETag") }); + } catch { + return; + } + await new Promise((resolve) => setTimeout(resolve, gapMs)); + } +} + +/** + * Shows a change immediately and undoes it if the server refuses. + * `change(data)` returns the new version of the data saved for `url`. + */ +export async function optimistic(url, change, send, render) { + const before = await readCache(url); + if (!before) return send(); + const after = change(before.data); + // No etag: the next check must fetch, because the server's copy has changed. + await writeCache(url, { data: after, etag: null }); + render(after, { stale: true }); + try { + const response = await send(); + if (!response.ok) throw new Error(`${response.status}`); + return response; + } catch (error) { + await writeCache(url, before); + render(before.data, { stale: false }); + throw error; + } +} + +/** Refreshes now, when the tab comes back, and on a timer while it's visible. Returns a stop function. */ +export function keepFresh(refresh, { everyMs = 30000 } = {}) { + const tick = () => { if (!document.hidden) refresh(); }; + const onVisible = () => tick(); + document.addEventListener("visibilitychange", onVisible); + const timer = setInterval(tick, everyMs); + tick(); + return () => { + clearInterval(timer); + document.removeEventListener("visibilitychange", onVisible); + }; +} +``` + +### Putting it together + +```javascript +// app.js +import { keepFresh, openCache, optimistic, prefetch, swr } from "./swr.js"; + +const list = document.querySelector("#mail"); + +function draw({ mail }, { stale }) { + list.dataset.stale = stale; + list.replaceChildren(...mail.map((m) => { + const row = document.createElement("li"); + row.dataset.id = m.id; + row.className = m.isRead ? "read" : "unread"; + row.textContent = m.subject; // textContent, so mail can't inject HTML + row.onclick = () => markRead(m.id).catch(() => {}); + return row; + })); +} + +const markRead = (id) => optimistic( + "/api/bootstrap", + (data) => ({ ...data, mail: data.mail.map((m) => (m.id === id ? { ...m, isRead: true } : m)) }), + () => fetch(`/api/mail/${encodeURIComponent(id)}/read`, { method: "POST" }), + draw, +); + +export async function start(userId) { + await openCache(userId); + keepFresh(async () => { + const data = await swr("/api/bootstrap", draw, { + onError: (error, hasSaved) => { + if (!hasSaved) list.textContent = "Can't load your mail right now."; + }, + }).catch(() => null); + if (data) prefetch(data.mail.slice(0, 5).map((m) => `/api/mail/${encodeURIComponent(m.id)}`)); + }); +} +``` + +If you show mail as HTML, **sanitize it first** and never insert `body.content` directly, because it's +written by whoever sent it. `textContent`, as above, is the safe default. + +### Open without the network + +A service worker keeps the app's own files, so the page opens offline. It only handles your static files, +and leaves `/api/` alone so that private data stays under `swr.js`'s control. + +```javascript +// sw.js +const VERSION = "app-v1"; // change on every release +const FILES = ["/", "/app.js", "/swr.js"]; + +self.addEventListener("install", (event) => { + event.waitUntil(caches.open(VERSION).then((cache) => cache.addAll(FILES))); + self.skipWaiting(); +}); + +self.addEventListener("activate", (event) => { + event.waitUntil( + caches.keys() + .then((keys) => Promise.all(keys.filter((k) => k !== VERSION).map((k) => caches.delete(k)))) + .then(() => self.clients.claim()), + ); +}); + +self.addEventListener("fetch", (event) => { + const url = new URL(event.request.url); + if (event.request.method !== "GET" || url.origin !== location.origin) return; + if (url.pathname.startsWith("/api/")) return; + event.respondWith(caches.match(event.request).then((hit) => hit || fetch(event.request))); +}); +``` + +Register it from your page with `navigator.serviceWorker.register("/sw.js")`. + +### Rules for the frontend + +- **One database per user, cleared on sign-out.** Call `clearCache(userId)`, or the next person on a shared + computer could read the previous user's mail. IndexedDB isn't encrypted. +- **Respect `Retry-After`.** If `error.retryAfter` is set, wait that long before trying again. +- **Don't poll too often.** `keepFresh` stops while the tab is hidden, and 30 seconds is a fair start. +- **There's no push here.** Teams and Outlook get updates over their own push connections, so this approach + has a delay up to your polling interval. + +## Choosing the times + +| Data | `fresh` | `stale` | Why | +|---|---|---|---| +| Startup bundle | 5 s | 10 min | Reads shared results, so it can be rebuilt often | +| Mail and chat lists | 30 s | 10 min | Changes often, but a short delay is acceptable | +| One message | 5 min | 1 hour | Rarely changes after it arrives | +| Folders, teams, people | 5-15 min | 1 day | Rarely changes | + +These are sensible starting points, not measured values. Adjust them to your app. + +## See also + +- [caching.md](caching.md) covers `SQLiteCache` and `stream()`, which fetch only what changed. They're more + efficient than re-fetching lists, so consider them once this layout works for you. diff --git a/docs/reference.md b/docs/reference.md index 782e44d..2fb67e8 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -29,6 +29,7 @@ Verified end-to-end against a live locked-down EDU tenant. | Teams activity | `activity()`, `mentions()`, `call_history()`, `teams_presence(ids)` | Teams' own APIs, undocumented, no Graph equivalent or fallback | | Extras | `people()`, `reminders(start, end)`, `categories()`, `mail_tips(addresses)`, `recent_files()`, `shared_with_me()` | `/me/people`, `reminderView`, `masterCategories`, `getMailTips`, `/me/drive/recent`, `/me/drive/sharedWithMe` | | Mailbox settings | `mailbox_settings()`, `auto_replies()`, `working_hours()`, `mail_rules()` | `/me/mailboxSettings`, `messageRules`, read-only, through the Teams client | +| Behind an API | `outnote.api`: `ApiCache`, `ClientPool`, `respond`, `error_response` | optional, see [frontend-and-api.md](frontend-and-api.md) | | Search | `search_emails`, `search_files`, `search_messages`, `search_people`, `search(q, entity)` | `/search/query` | | Robustness | `batch(requests)`, `delta(path, delta_link)` | `/$batch` (20 per call, 4 calls at once, throttled sub-requests retried), `/delta` | | Sync | `stream(kind, cursor)`, `SQLiteCache(path, client)` | Graph delta and Teams' sync cursors, see [caching.md](caching.md) | @@ -55,4 +56,5 @@ on many tenants (403). The meeting *chat* works without them. **undocumented APIs** that can change without notice; `native=False` keeps other reads on Graph. See [clients.md](clients.md) for the FOCI client/scope map and how it was found, and -[caching.md](caching.md) for speed, sync and caching. +[caching.md](caching.md) for speed, sync and caching. Building a web app or API? See +[frontend-and-api.md](frontend-and-api.md). diff --git a/src/outnote/api.py b/src/outnote/api.py new file mode 100644 index 0000000..59d2a7c --- /dev/null +++ b/src/outnote/api.py @@ -0,0 +1,211 @@ +"""Optional helpers for running OutNote behind your own API. Standard library only, framework-free, +and nothing here runs unless you import it, so the client itself stays stateless. + + from outnote.api import ApiCache, ClientPool, error_response, respond + + clients = ClientPool(load_token=my_db.load, save_token=my_db.save) + cache = ApiCache(fresh=30, stale=600) + + entry = cache.get(user, "mail", lambda: clients.get(user).emails(top=25)) + status, headers, body = respond(entry, request_headers.get("If-None-Match")) + +See docs/frontend-and-api.md. +""" + +import hashlib +import json +import logging +import threading +import time +from collections import OrderedDict +from concurrent.futures import ThreadPoolExecutor +from dataclasses import dataclass +from typing import Any + +from entrance import Broker + +from ._graph import OutNote + +__all__ = ["ApiCache", "ClientPool", "Entry", "error_response", "respond"] + +log = logging.getLogger("outnote.api") + + +@dataclass +class Entry: + """One cached result: the data, its JSON `body`, an `etag`, and how old it is.""" + + body: bytes + etag: str + at: float + data: Any + + @property + def age(self): + return time.monotonic() - self.at + + +class ApiCache: + """A per-user, in-memory cache of results. Safe to share between threads. + + Up to `fresh` seconds old, a result is answered from memory. Up to `stale` seconds, it's answered + from memory and refreshed in the background. Older than that, the caller waits for a new one, and + gets the old one only if the refresh fails. Identical requests share one fetch. + + It holds real mail and chats in memory, keyed by the `user` you pass, so that value must come from + your own authentication. For several servers, keep this logic but store entries somewhere shared.""" + + def __init__(self, fresh=30, stale=600, max_entries=5000, workers=8): + self.fresh, self.stale, self.max_entries = fresh, stale, max_entries + self._entries: OrderedDict = OrderedDict() + self._running: dict = {} # key -> Future, so identical requests share one fetch + self._generation: dict = {} # user -> counter, so a slow old fetch can't overwrite a write + self._lock = threading.RLock() + self._pool = ThreadPoolExecutor(workers, thread_name_prefix="outnote-api") + + def get(self, user, name, fetch, fresh=None, stale=None): + """The `Entry` for this user's `name`, calling `fetch()` if needed. `fetch` must return + JSON-serializable data. Raises whatever `fetch` raises if there's nothing old to fall back on.""" + fresh = self.fresh if fresh is None else fresh + stale = self.stale if stale is None else stale + key = (user, name) + with self._lock: + entry = self._entries.get(key) + if entry and entry.age < fresh: + self._entries.move_to_end(key) + return entry + future = self._refresh(key, fetch) + if entry and entry.age < stale: + return entry # the refresh carries on in the background + try: + return future.result() + except Exception: + if entry: # something old beats an error + log.warning("serving old data for %s after a failed refresh", name, exc_info=True) + return entry + raise + + def invalidate(self, user, prefix=""): + """Forget this user's results whose name starts with `prefix`. Call it after every write that + could change them, and with no prefix when the user signs out.""" + with self._lock: + self._generation[user] = self._generation.get(user, 0) + 1 + for key in [k for k in self._entries if k[0] == user and k[1].startswith(prefix)]: + del self._entries[key] + for key in [k for k in self._running if k[0] == user]: + del self._running[key] + + def close(self): + """Stop the background threads, for a clean shutdown.""" + self._pool.shutdown(wait=False, cancel_futures=True) + + def _refresh(self, key, fetch): + future = self._running.get(key) + if not future: + generation = self._generation.get(key[0], 0) + future = self._pool.submit(self._load, key, fetch, generation) + self._running[key] = future + return future + + def _load(self, key, fetch, generation): + try: + data = fetch() + body = json.dumps(data, separators=(",", ":")).encode() + etag = '"' + hashlib.sha256(body).hexdigest()[:32] + '"' + entry = Entry(body, etag, time.monotonic(), data) + with self._lock: + if self._generation.get(key[0], 0) == generation: + self._entries[key] = entry + self._entries.move_to_end(key) + while len(self._entries) > self.max_entries: + self._entries.popitem(last=False) + return entry + finally: + with self._lock: + if self._generation.get(key[0], 0) == generation: # a newer fetch keeps its place + self._running.pop(key, None) + + +class ClientPool: + """One `OutNote` client per user, built from refresh tokens you store yourself. + + `load_token(user)` returns the user's refresh token. `save_token(user, token)` is called whenever + it rotates: save it, or that user may eventually have to sign in again. Refresh tokens work like + passwords, so keep them encrypted. Token requests for one user run one at a time, so threads can't + use a token that has just been replaced.""" + + def __init__(self, load_token, save_token=None, tenant="common", native=True, max_clients=1000): + self.load_token, self.save_token = load_token, save_token + self.tenant, self.native, self.max_clients = tenant, native, max_clients + self._clients: OrderedDict = OrderedDict() + self._lock = threading.Lock() + + def get(self, user): + """The client for `user`, created on first use. The least recently used are dropped past + `max_clients`.""" + with self._lock: + client = self._clients.get(user) + if client: + self._clients.move_to_end(user) + return client + token = self.load_token(user) + if not token: + raise LookupError(f"no refresh token for {user!r}") + client = OutNote(self._tokens(user, token), native=self.native) + with self._lock: + client = self._clients.setdefault(user, client) + self._clients.move_to_end(user) + while len(self._clients) > self.max_clients: + self._clients.popitem(last=False) + return client + + def drop(self, user): + """Forget a user's client and its tokens in memory. Call it when the user signs out, and delete + the stored refresh token yourself.""" + with self._lock: + self._clients.pop(user, None) + + def _tokens(self, user, refresh_token): + broker = Broker(refresh_token, self.tenant) + lock = threading.Lock() + + def token(client_id, *scope): + with lock: + before = broker.refresh_token + access = broker(client_id, *scope) + if broker.refresh_token != before and self.save_token: + try: + self.save_token(user, broker.refresh_token) + except Exception: # the old token usually still works, so keep serving + log.exception("could not save the rotated refresh token for a user") + return access + + return token + + +def _matches(if_none_match, etag): + if not if_none_match: + return False + if if_none_match.strip() == "*": + return True + return any(tag.strip().removeprefix("W/") == etag for tag in if_none_match.split(",")) + + +def respond(entry, if_none_match=None): + """`(status, headers, body)` for an `Entry`: 304 with no body if the browser's copy still matches + the request's `If-None-Match`, otherwise 200 with the JSON. `Cache-Control: private` keeps shared + caches from storing it.""" + headers = {"ETag": entry.etag, "Cache-Control": "private, no-cache", "Age": str(int(entry.age))} + if _matches(if_none_match, entry.etag): + return 304, headers, b"" + return 200, {**headers, "Content-Type": "application/json"}, entry.body + + +def error_response(error): + """`(status, headers, body)` for a `GraphError`. 403, 404 and 429 pass through, with `Retry-After` + when Graph asked for a wait; anything else becomes 502, because it's a failure upstream.""" + status = error.status if error.status in (403, 404, 429) else 502 + headers = {"Content-Type": "application/json"} + if error.retry_after: + headers["Retry-After"] = str(int(error.retry_after)) + return status, headers, json.dumps({"error": str(error)}).encode() diff --git a/tests/test_api.py b/tests/test_api.py new file mode 100644 index 0000000..1b18ad1 --- /dev/null +++ b/tests/test_api.py @@ -0,0 +1,253 @@ +"""outnote.api: the cache, the client pool and the response helpers. No network.""" + +import json +import threading +import time + +import pytest + +import outnote +from outnote import api +from outnote.api import ApiCache, ClientPool, error_response, respond + + +def test_fresh_answers_from_memory(): + calls = [] + c = ApiCache(fresh=60) + fetch = lambda: calls.append(1) or {"n": len(calls)} # noqa: E731 + c.get("u", "a", fetch) + assert c.get("u", "a", fetch).data == {"n": 1} and len(calls) == 1 + + +def test_stale_answers_at_once_and_refreshes_in_the_background(): + c = ApiCache(fresh=0, stale=60) + c.get("u", "a", lambda: {"v": 1}) + started = time.perf_counter() + done = threading.Event() + + def slow(): + time.sleep(0.2) + done.set() + return {"v": 2} + + assert c.get("u", "a", slow).data == {"v": 1} + assert time.perf_counter() - started < 0.1 + assert done.wait(2) + time.sleep(0.05) + assert c.get("u", "a", lambda: {"v": 3}, fresh=60).data == {"v": 2} + + +def test_expired_waits_for_new_data(): + c = ApiCache(fresh=0, stale=0) + c.get("u", "a", lambda: {"v": 1}) + assert c.get("u", "a", lambda: {"v": 2}).data == {"v": 2} + + +def test_users_never_share_results(): + c = ApiCache() + c.get("alice", "mail", lambda: {"who": "alice"}) + assert c.get("bob", "mail", lambda: {"who": "bob"}).data == {"who": "bob"} + + +def test_identical_requests_share_one_fetch(): + c = ApiCache() + calls = [] + + def slow(): + calls.append(1) + time.sleep(0.2) + return {} + + threads = [threading.Thread(target=lambda: c.get("u", "x", slow)) for _ in range(10)] + [t.start() for t in threads] + [t.join() for t in threads] + assert len(calls) == 1 + + +def boom(): + raise RuntimeError("down") + + +def test_failures_serve_old_data_raise_otherwise_and_are_not_remembered(): + c = ApiCache(fresh=0, stale=0) + c.get("u", "x", lambda: {"v": 1}) + assert c.get("u", "x", boom).data == {"v": 1} + empty = ApiCache() + with pytest.raises(RuntimeError): + empty.get("u", "y", boom) + assert empty.get("u", "y", lambda: {"v": 2}).data == {"v": 2} + + +def test_invalidate_beats_a_slow_old_read(): + c = ApiCache() + release = threading.Event() + + def old(): + release.wait(2) + return {"v": "old"} + + t = threading.Thread(target=lambda: c.get("u", "m", old)) + t.start() + time.sleep(0.05) + c.invalidate("u", "m") + assert c.get("u", "m", lambda: {"v": "new"}).data == {"v": "new"} + release.set() + t.join() + time.sleep(0.05) + assert c.get("u", "m", lambda: {"v": "x"}).data == {"v": "new"} + + +def test_invalidate_uses_prefix_and_only_that_user(): + c = ApiCache() + c.get("a", "mail", lambda: 1) + c.get("a", "mail/1", lambda: 1) + c.get("a", "chats", lambda: 1) + c.get("b", "mail", lambda: 2) + c.invalidate("a", "mail") + assert set(c._entries) == {("a", "chats"), ("b", "mail")} + c.invalidate("a") + assert set(c._entries) == {("b", "mail")} + + +def test_size_is_bounded_and_nothing_is_left_running(): + c = ApiCache(max_entries=3) + for i in range(6): + c.get("u", str(i), lambda i=i: i) + time.sleep(0.05) + assert len(c._entries) == 3 and not c._running + + +# --- responses -------------------------------------------------------------------- +def entry(): + return ApiCache().get("u", "x", lambda: {"a": 1}) + + +def test_respond_sends_json_privately(): + e = entry() + status, headers, body = respond(e) + assert status == 200 and json.loads(body) == {"a": 1} + assert headers["ETag"] == e.etag and "private" in headers["Cache-Control"] + assert headers["Content-Type"] == "application/json" + + +@pytest.mark.parametrize("template", ["{}", "W/{}", '"other", {}', "*"]) +def test_respond_304_when_the_copy_matches(template): + e = entry() + status, headers, body = respond(e, template.format(e.etag)) + assert status == 304 and body == b"" and headers["ETag"] == e.etag + + +def test_respond_200_when_the_copy_differs(): + assert respond(entry(), '"old"')[0] == 200 + + +def test_etag_changes_with_the_data(): + c = ApiCache() + assert c.get("u", "a", lambda: 1).etag != c.get("u", "b", lambda: 2).etag + + +def test_error_responses(): + status, headers, body = error_response(outnote.GraphError(429, "busy", retry_after=7.5)) + assert status == 429 and headers["Retry-After"] == "7" and b"busy" in body + assert error_response(outnote.GraphError(404, "gone"))[0] == 404 + assert error_response(outnote.GraphError(403, "no"))[0] == 403 + status, headers, _ = error_response(outnote.GraphError(500, "oops")) + assert status == 502 and "Retry-After" not in headers + + +# --- client pool ------------------------------------------------------------------ +class FakeBroker: + """Rotates its refresh token on every token request, like the real one can.""" + + created: list = [] + + def __init__(self, refresh_token, tenant="common", store=None): + self.refresh_token, self.tenant, self.calls = refresh_token, tenant, [] + FakeBroker.created.append(self) + + def __call__(self, client_id, *scope): + self.calls.append((client_id, *scope)) + self.refresh_token += "+" + return f"access-for-{client_id}" + + +@pytest.fixture +def broker(monkeypatch): + FakeBroker.created = [] + monkeypatch.setattr(api, "Broker", FakeBroker) + + +def test_pool_reuses_one_client_per_user(broker): + loaded = [] + pool = ClientPool(lambda u: loaded.append(u) or f"rt-{u}") + a = pool.get("a") + assert pool.get("a") is a and pool.get("b") is not a + assert loaded == ["a", "b"] + assert FakeBroker.created[0].refresh_token == "rt-a" + + +def test_pool_saves_rotated_tokens(broker): + saved = [] + pool = ClientPool(lambda u: "rt", lambda u, t: saved.append((u, t))) + client = pool.get("a") + assert client._tp("office") == "access-for-office" + client._tp("sites", "https://x/.default") + assert saved == [("a", "rt+"), ("a", "rt++")] + assert FakeBroker.created[0].calls[1] == ("sites", "https://x/.default") + + +def test_a_failed_save_does_not_break_the_request(broker): + def bad(user, token): + raise OSError("db down") + + assert ClientPool(lambda u: "rt", bad).get("a")._tp("x") == "access-for-x" + + +def test_pool_is_brokered_so_native_stays_available(broker): + assert ClientPool(lambda u: "rt").get("a").native is True + assert ClientPool(lambda u: "rt", native=False).get("b").native is False + + +def test_missing_token_is_clear(broker): + with pytest.raises(LookupError, match="no refresh token"): + ClientPool(lambda u: None).get("a") + + +def test_drop_and_limit(broker): + pool = ClientPool(lambda u: "rt", max_clients=2) + first = pool.get("a") + pool.drop("a") + assert pool.get("a") is not first + pool.get("b") + pool.get("c") + assert set(pool._clients) == {"b", "c"} + + +def test_token_requests_for_one_user_run_one_at_a_time(broker): + client = ClientPool(lambda u: "rt").get("a") + inside, peak = [0], [0] + original = FakeBroker.__call__ + + def slow(self, client_id, *scope): + inside[0] += 1 + peak[0] = max(peak[0], inside[0]) + time.sleep(0.01) + inside[0] -= 1 + return original(self, client_id, *scope) + + FakeBroker.__call__ = slow + try: + threads = [threading.Thread(target=client._tp, args=("x",)) for _ in range(10)] + [t.start() for t in threads] + [t.join() for t in threads] + finally: + FakeBroker.__call__ = original + assert peak[0] == 1 + + +def test_importing_outnote_alone_does_not_load_the_helpers(): + import subprocess + import sys + + code = "import sys, outnote; print('outnote.api' in sys.modules)" + assert subprocess.check_output([sys.executable, "-c", code], text=True).strip() == "False"