vincent/gerbeur
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v3: comments say what the code can't — the documentation pass wanted JSDoc on every export and every field of an exported interface, which filled the code with restatements ("The dump.", "Whether it is loading.", "The props of X.", "Renders the X.") and module docs that told a reader nothing ("The hot and new feeds, and the props every main feed of the index takes."); some were wrong as well as vague. Every comment in api/, shared/ and src/ is rewritten under one rule, now stated in the README's "Comments" section: every module and export still has a JSDoc, and it gives context (who uses it and where), usage (what a caller must know: a precondition, what it leaves to the caller, a side effect) or its place in the chain (where its input comes from, where its output goes); a field, parameter, private function or local gets one only when it adds to its parent's, and context about a whole type goes on the type; a type's doc is phrased from the value's side ("Returned to Y by X when Z", "Passed to Y by X"); full sentences, as short as they can be, no label-colon-list; // goes wherever the code isn't obvious and says why, and the section banners and narration go. Every claim was checked against the code, which turned up some forty comments that were wrong: DumpCard's claimed it was only used by the hot and new feeds, the WebSocket welcome claimed to be a socket's first message (presence comes first), UpdateUserRequest said null removes a description (it keeps it), deletedDumpIds leaves out that it also holds dumps made private, THEME_COLOR claimed to mirror index.html's, and the like. The routers' JSDoc now says where they are mounted and what becomes of a thrown APIException. doc-lint.ts lets a field without a doc through; a module or export without one still fails. No code changes; 204 backend and 628 frontend tests pass, and doc:lint, deno check, deno lint and tsc are clean.

Browse Source 
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
khannurien
2026-09-29 14:31:14 +00:00
parent 42e0356d21
commit 0d4e344d77
287 changed files with 5679 additions and 5135 deletions
Download Patch File Download Diff File Expand all files Collapse all files

73
src/hooks/auth/useAuth.ts
View File

@@ -1,5 +1,6 @@
/**
* The session, and requests made with it.
* Gives components the session, and the functions that sign in, sign out and
* make requests with its token.
*
* @module
*/
@@ -16,16 +17,17 @@ import {
storeSession,
} from "../../utils/auth/storage.ts";
/** What {@link useAuth} returns. */
/**
* Returned by {@link useAuth} to any component that needs the session. Its
* functions are stable until the session's token changes.
*/
export interface UseAuthResult {
/** The signed-in user, null when signed out. */
user: SelfUser | null;
/** The session token. */
token: string | null;
/**
* The token for file and thumbnail URLs, where it is visible in the query
* string. Sessions from before media tokens fall back to the session token
* until AuthProvider fetches one.
* The token for file and thumbnail URLs, where it shows in the query string.
* A session from before media tokens falls back to the session token until
* AuthProvider fetches one.
*/
mediaToken: string | null;
/** Starts a session from a sign-in or sign-up response, in every tab. */
@@ -36,25 +38,25 @@ export interface UseAuthResult {
* must not sign those out.
*/
logout: () => void;
/** Merges `patch` into the current session, in memory and in storage. */
/**
* Merges `patch` into the session, in memory and in storage. The profile page
* uses it for a new avatar or email, the password dialog for fresh tokens.
*/
updateSession: (patch: Partial<Session>) => void;
/**
* `fetch` with the session's token, and a JSON content type unless the body
* is FormData. An expired token, or a 401, ends the session; the former
* answers a synthetic 401 without calling the server.
* Calls `fetch` with the session's token, and a JSON content type unless the
* body is FormData. An expired token, or a 401, ends the session. An expired
* token answers a 401 without calling the server.
*/
authFetch: (input: RequestInfo, init?: RequestInit) => Promise<Response>;
/**
* `authFetch` for multipart uploads that need a progress bar.
* Works like `authFetch` for a multipart upload that shows progress, as the
* dump creation dialog's file upload does. It goes through XHR, since `fetch`
* reports nothing until the whole body is sent. It still answers a
* `Response`, so callers use `expectOk` as usual.
*
* `fetch` reports nothing until the whole body is on the wire, which for a 50
* MB dump on a phone is a long silence — so this goes through XHR, whose
* `upload.progress` events fire as bytes leave. The result is wrapped back
* into a real `Response` so callers keep using `expectOk` unchanged.
*
* `onProgress` receives a 0–1 fraction, or `null` once the body is fully sent
* and we are waiting on the server (the length is unknown for chunked bodies,
* and "100%, still waiting" reads as a stall).
* `onProgress` receives a fraction from 0 to 1, or `null` once the body is
* sent and the server is working, or when the length is unknown.
*/
authUpload: (
url: string,
@@ -64,7 +66,10 @@ export interface UseAuthResult {
) => Promise<Response>;
}
/** Returns the session and what acts on it. */
/**
* Returns the session and the functions that act on it. It must be called
* under `AuthProvider`.
*/
export function useAuth(): UseAuthResult {
const { authResponse, setAuthResponse } = useContext(AuthContext);
@@ -73,9 +78,6 @@ export function useAuth(): UseAuthResult {
storeSession(response);
}, [setAuthResponse]);
// Ends the session this render holds. A 401 can land after the session has
// moved on to fresh tokens (a password change, here or in another tab), and
// must not sign those out.
const sessionToken = authResponse?.token;
const logout = useCallback(() => {
setAuthResponse((prev) => prev?.token === sessionToken ? null : prev);
@@ -99,7 +101,7 @@ export function useAuth(): UseAuthResult {
if (token && isTokenExpired(token)) {
logout();
// Return a synthetic 401 so callers handle it consistently
// Callers already handle a 401 from the server; this looks the same.
return new Response(null, { status: 401 });
}
@@ -109,10 +111,8 @@ export function useAuth(): UseAuthResult {
...init,
headers: {
...(init.headers ?? {}),
// Only attach a token when we actually have one — avoids sending a
// `Bearer undefined` header that the server would reject as invalid.
...(token ? { Authorization: `Bearer ${token}` } : {}),
// Let the browser set Content-Type for FormData (it includes the boundary)
// The browser sets FormData's Content-Type, with its boundary.
...(isFormData ? {} : { "Content-Type": "application/json" }),
},
});
@@ -141,7 +141,7 @@ export function useAuth(): UseAuthResult {
const xhr = new XMLHttpRequest();
xhr.open(method, url);
if (token) xhr.setRequestHeader("Authorization", `Bearer ${token}`);
// Content-Type is left to the browser so the multipart boundary is set.
// The browser sets the Content-Type, with the multipart boundary.
xhr.upload.addEventListener("progress", (e) => {
onProgress(e.lengthComputable ? e.loaded / e.total : null);
@@ -157,8 +157,8 @@ export function useAuth(): UseAuthResult {
}),
);
});
// Mirrors what `fetch` throws on a network failure, so the shared
// `friendlyFetchError` path renders it the same way.
// The error `fetch` throws on a network failure, so that
// `friendlyFetchError` reports it the same way.
xhr.addEventListener(
"error",
() => reject(new TypeError("Failed to fetch")),
@@ -184,16 +184,19 @@ export function useAuth(): UseAuthResult {
};
}
/** What {@link useRequiredAuth} returns: {@link UseAuthResult} with a user. */
/**
* Returned by {@link useRequiredAuth}. It is {@link UseAuthResult} with a user
* that can't be null.
*/
export interface UseRequiredAuthResult extends UseAuthResult {
/** The signed-in user. */
user: SelfUser;
}
/**
* Returns the session, for a page behind a sign-in.
* Returns the session, for a page that `RestrictedLoggedIn` guards, such as
* `DumpEdit`, so it needn't check for a user.
*
* @throws {Error} When no one is signed in: the route should have guarded it.
* @throws {Error} When no one is signed in, which means the route has no guard.
*/
export function useRequiredAuth(): UseRequiredAuthResult {
const {