about summary refs log tree commit diff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/SKILL.md97
1 files changed, 97 insertions, 0 deletions
diff --git a/docs/SKILL.md b/docs/SKILL.md
index dade13c..1a28a66 100644
--- a/docs/SKILL.md
+++ b/docs/SKILL.md
@@ -115,6 +115,74 @@ Use `utoipa` + `utoipa-axum`, not a hand-maintained spec file:
 - This way a route or schema change that doesn't update its
   `#[utoipa::path]`/`ToSchema` is a compile error or an obviously
   incomplete diff, not spec drift noticed weeks later.
+- When most endpoints require the same thing (a bearer token, an API
+  key), set it once as the document default -- `#[openapi(security(
+  ("scheme_name" = [])), ...)]` on the `#[derive(utoipa::OpenApi)]`
+  struct -- instead of repeating `security(...)` on every
+  `#[utoipa::path]`. The handful of endpoints that must NOT require it
+  (health check, version, the endpoint that hands out the credential in
+  the first place) override with an empty `security()` of their own;
+  an absent `security(...)` on an operation inherits the document
+  default, a present-but-empty one overrides to "none" -- standard
+  OpenAPI semantics, not utoipa-specific. Audit every operation's
+  resolved `security` in the generated `/openapi.json` after making this
+  change (`"security": [...]` present vs. absent per operation) -- it's
+  easy to silently document a public endpoint as requiring auth, or
+  vice versa, since nothing fails to compile either way.
+- A response shape repeated across many handlers (e.g. "401, missing or
+  invalid token", always the same error body type) doesn't need
+  hand-copying into every `responses(...)` list: give it its own
+  `#[derive(utoipa::IntoResponses)] #[response(status = 401, ...)]`
+  marker struct wrapping the real body type (`struct Unauthorized(
+  #[to_schema] ApiError)`), then reference it bare inside any handler's
+  `responses(...)` (`responses(Unauthorized, (status = 200, ...))`). The
+  marker struct is never constructed at runtime (the actual response
+  still comes from wherever the rejection/error is produced, e.g. an
+  extractor's `FromRequestParts` impl) -- `#[allow(dead_code)]` it with
+  a comment saying why, rather than leaving an unexplained warning or
+  actually constructing a throwaway value just to silence one.
+
+## Authentication/authorization
+
+- Make requiring a token **opt-in per handler**, not a blanket
+  middleware layer: a custom extractor (`struct AuthToken; impl
+  FromRequestParts<S> for AuthToken`) that verifies/rejects in
+  `from_request_parts`. A handler adds `token: AuthToken` (or `_token:
+  AuthToken` if it only needs the gate, not the claims) to its
+  parameter list to require one; omitting the parameter is what makes
+  it optional, with no central route-list to keep in sync. Non-body
+  extractors like this can go anywhere in the parameter list except
+  after a body-consuming one (`Json<T>` etc. must stay last).
+- If some data is "public" and some isn't, don't let that become "some
+  endpoints need a token and some don't" -- keep the token check
+  universal (cheap: local signature verification, no network call) and
+  make "is this specific resource public" a second, independent
+  decision the handler makes afterward, with its own cache, only
+  calling out to an authorization service for the resources that
+  actually need it.
+- A resource addressed by `(container, item)` where `container` can
+  belong to more than one underlying category (e.g. a "dataset" that's
+  sometimes one database table, sometimes another) should resolve
+  `container`'s category **first**, as its own lookup, before ever
+  looking up `item`. Resolving `item` by guessing across categories
+  (try category A's lookup, fall back to category B's) risks a same-named
+  collision silently returning the wrong thing -- resolving `container`
+  first instead means only a much smaller set of names (containers) is
+  ever disambiguated across categories, not every item name ever.
+- A dev-only endpoint that hands out a credential (e.g. proxies an
+  auth service's own token grant for a well-known test user) needs at
+  least two independent config conditions to enable it (e.g. "dev mode
+  on" AND "bound to loopback only"), not one flag -- and the condition
+  should be a plain function with its own unit tests
+  (`Config::dev_token_enabled()`), not inline `if` logic duplicated at
+  each call site. Register the route conditionally at startup rather
+  than registering it unconditionally and rejecting inside the
+  handler: an unregistered route is a 404 and genuinely absent from the
+  generated OpenAPI spec, so a production deployment doesn't even
+  document that a token-issuing endpoint could exist. Default any
+  credentials this endpoint needs to the target service's own published
+  "dev fixtures" (a well-known test client/user every checkout of that
+  service already has) so it works with zero extra configuration.
 
 ## Testing
 
@@ -148,6 +216,35 @@ Two parallel suites exercising the same endpoints:
   once per test *file*, not just once overall -- that's expected, not
   a sign the fix didn't work; what matters is that repeated calls
   inside one file (or one real server process) stay fast after it.
+- If endpoints need a bearer token and the service has a dev-only
+  token-issuing endpoint (see "Authentication/authorization" above),
+  have the test suite fetch its own token from it rather than requiring
+  a human to mint and export one by hand first. Try that first, fall
+  back to an externally-provided token (an env var) for a setup that
+  doesn't want dev mode on even for tests -- so the suite still works
+  unmodified either way. For the in-process Rust suite this means
+  calling the router's own dev endpoint via the same `oneshot` plumbing
+  used for every other request; for a suite that spawns the real
+  binary as a subprocess (Python, here), it means starting that
+  specific test's subprocess with the dev-mode env vars set so it can
+  answer its own token request over the same HTTP connection the test
+  already uses.
+- Mutating process-wide state (env vars, global config) from a test is
+  only safe when nothing else in the same process can read or write
+  that same state concurrently. A single compiled test binary (one
+  `tests/*.rs` file) runs its `#[tokio::test]`/`#[test]` functions
+  concurrently on different threads by default -- so a test that must
+  flip an env var through several values keeps all of those mutations
+  in one sequential test function, with a comment saying why, rather
+  than splitting them across multiple test functions in the same file.
+  A suite that instead spawns a fresh subprocess per test class (own
+  process, own env, e.g. Python's `ServerTestCase`) doesn't have this
+  problem -- each class can set its own env independently and safely.
+  On edition 2024, `std::env::set_var`/`remove_var` are `unsafe fn`
+  (exactly because of this hazard); wrap each call in its own tiny
+  `unsafe { ... }` with a `// SAFETY:` comment pointing at whichever of
+  the two guarantees above makes it sound here, rather than one broad
+  `unsafe` block around unrelated code.
 
 ## Guix packaging