mirror of
https://github.com/outline/outline.git
synced 2026-11-22 14:01:41 +03:00
chore: Improve ApiClient class (#12720)
* refactor: Decouple ApiClient from auth store and document its public surface Move logout policy out of the transport layer: ApiClient now notifies a registered handler on unauthenticated responses (401 / suspended 403) instead of calling stores.auth.logout directly, breaking the AuthStore -> client -> stores import cycle. AuthStore owns the logout flags and registers the handler. Also add JSDoc across the public surface (setShareId, fetch, get, post, client). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * refactor: Extend request deduplication to PUT via shared helper Extract the in-flight dedup logic into a private deduplicate() helper and route both post() and the new put() through it. The dedup key now includes the HTTP method so a POST and PUT to the same path can't collide. Multipart uploads continue to bypass deduplication. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * Improve types * refactor: Improve ApiClient type safety and address review feedback - Add a Method union ("GET" | "POST" | "PUT") for fetch/deduplicate, replacing the loose string type. Narrowed to methods whose bodies are actually serialized, so callers aren't given false support for PATCH/DELETE. - Type previously implicit-any locals (modifiedPath, urlToFetch, isJson). - Extract an ApiErrorResponse interface for the parsed error payload. - Register the unauthorized handler before fetchAuth() so a 401 on the initial auth request triggers the logout policy. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
1 parent
62d5c25bd3
commit
061aee0225
3 files changed
+123
-29
No files matched your search
@@ -92,6 +92,13 @@ export default class AuthStore extends Store<Team> {
|
||||
const data: PersistedData = Storage.get(this.name) || {};
|
||||
|
||||
this.rehydrate(data);
|
||||
|
||||
client.setUnauthorizedHandler((reason) =>
|
||||
reason === "user_suspended"
|
||||
? this.logout({ savePath: false, revokeToken: false, clearCache: true })
|
||||
: this.logout({ savePath: true, revokeToken: false, clearCache: false })
|
||||
);
|
||||
|
||||
void this.fetchAuth();
|
||||
|
||||
// persists this entire store to localstorage whenever any keys are changed
|
||||
|
||||
+115
-29
@@ -6,7 +6,6 @@ import type { JSONObject } from "@shared/types";
|
||||
import { Scope } from "@shared/types";
|
||||
import { version } from "../../package.json";
|
||||
import env from "~/env";
|
||||
import stores from "~/stores";
|
||||
import Logger from "./Logger";
|
||||
import download from "./download";
|
||||
import {
|
||||
@@ -31,6 +30,22 @@ type Options = {
|
||||
baseUrl?: string;
|
||||
};
|
||||
|
||||
/** An HTTP method supported by the API client. */
|
||||
type Method = "GET" | "POST" | "PUT";
|
||||
|
||||
/** Shape of an error payload returned by the API. */
|
||||
interface ApiErrorResponse {
|
||||
message?: string;
|
||||
error?: string;
|
||||
data?: Record<string, unknown>;
|
||||
}
|
||||
|
||||
/** Reason the server rejected a request as unauthenticated. */
|
||||
export type UnauthorizedReason = "unauthorized" | "user_suspended";
|
||||
|
||||
/** Handler invoked when a request is rejected as unauthenticated. */
|
||||
type UnauthorizedHandler = (reason: UnauthorizedReason) => void | Promise<void>;
|
||||
|
||||
interface FetchOptions {
|
||||
download?: boolean;
|
||||
retry?: boolean;
|
||||
@@ -46,29 +61,60 @@ class ApiClient {
|
||||
|
||||
shareId?: string;
|
||||
|
||||
/** Map of in-flight POST requests for deduplication, keyed by path + body. */
|
||||
/** Map of in-flight requests for deduplication, keyed by method + path + body. */
|
||||
// oxlint-disable-next-line no-explicit-any
|
||||
private inflightRequests = new Map<string, Promise<any>>();
|
||||
|
||||
private onUnauthorized?: UnauthorizedHandler;
|
||||
|
||||
constructor(options: Options = {}) {
|
||||
this.baseUrl = options.baseUrl || "/api";
|
||||
}
|
||||
|
||||
/**
|
||||
* Sets the share identifier appended to subsequent requests, used to
|
||||
* authenticate access to publicly shared documents.
|
||||
*
|
||||
* @param shareId the share identifier, or undefined to clear it.
|
||||
*/
|
||||
setShareId = (shareId: string | undefined) => {
|
||||
this.shareId = shareId;
|
||||
};
|
||||
|
||||
/**
|
||||
* Registers a handler invoked when a request is rejected as unauthenticated
|
||||
* (a 401, or a 403 indicating the user was suspended). Used to keep
|
||||
* session/logout policy out of the transport layer.
|
||||
*
|
||||
* @param handler the handler to invoke.
|
||||
*/
|
||||
setUnauthorizedHandler = (handler: UnauthorizedHandler) => {
|
||||
this.onUnauthorized = handler;
|
||||
};
|
||||
|
||||
/**
|
||||
* Performs an HTTP request against the API, handling serialization, headers,
|
||||
* CSRF, retries, and error mapping.
|
||||
*
|
||||
* @param path the request path, relative to the base URL or an absolute URL.
|
||||
* @param method the HTTP method to use.
|
||||
* @param data the request payload, sent as a query string for GET requests
|
||||
* and as a JSON or multipart body otherwise.
|
||||
* @param options additional request options.
|
||||
* @returns the parsed JSON response, or undefined for downloads and empty responses.
|
||||
* @throws {RequestError} if the response status indicates failure.
|
||||
*/
|
||||
// oxlint-disable-next-line no-explicit-any
|
||||
fetch = async <T = any>(
|
||||
path: string,
|
||||
method: string,
|
||||
method: Method,
|
||||
data: JSONObject | FormData | undefined,
|
||||
options: FetchOptions = {}
|
||||
): Promise<T> => {
|
||||
let body: string | FormData | undefined;
|
||||
let modifiedPath;
|
||||
let urlToFetch;
|
||||
let isJson;
|
||||
let modifiedPath: string | undefined;
|
||||
let urlToFetch: string;
|
||||
let isJson = false;
|
||||
|
||||
if (this.shareId) {
|
||||
if (data instanceof FormData) {
|
||||
@@ -122,9 +168,7 @@ class ApiClient {
|
||||
};
|
||||
|
||||
// Add CSRF token to headers for mutating requests
|
||||
const isModifyingRequest = ["POST", "PUT", "PATCH", "DELETE"].includes(
|
||||
method
|
||||
);
|
||||
const isModifyingRequest = method === "POST" || method === "PUT";
|
||||
const canAccessWithReadOnly = AuthenticationHelper.canAccess(path, [
|
||||
Scope.Read,
|
||||
]);
|
||||
@@ -182,14 +226,10 @@ class ApiClient {
|
||||
return response.json();
|
||||
}
|
||||
|
||||
// Handle 401, log out user
|
||||
// Handle 401, notify session owner to log out
|
||||
if (response.status === 401) {
|
||||
if (!this.shareId) {
|
||||
await stores.auth.logout({
|
||||
savePath: true,
|
||||
clearCache: false,
|
||||
revokeToken: false,
|
||||
});
|
||||
await this.onUnauthorized?.("unauthorized");
|
||||
}
|
||||
throw new AuthorizationError();
|
||||
}
|
||||
@@ -208,14 +248,10 @@ class ApiClient {
|
||||
}
|
||||
|
||||
// Handle failed responses
|
||||
const error: {
|
||||
message?: string;
|
||||
error?: string;
|
||||
data?: Record<string, unknown>;
|
||||
} = {};
|
||||
const error: ApiErrorResponse = {};
|
||||
|
||||
try {
|
||||
const parsed = await response.json();
|
||||
const parsed: ApiErrorResponse = await response.json();
|
||||
error.message = parsed.message || "";
|
||||
error.error = parsed.error;
|
||||
error.data = parsed.data;
|
||||
@@ -238,11 +274,7 @@ class ApiClient {
|
||||
|
||||
if (response.status === 403) {
|
||||
if (error.error === "user_suspended") {
|
||||
await stores.auth.logout({
|
||||
savePath: false,
|
||||
revokeToken: false,
|
||||
clearCache: true,
|
||||
});
|
||||
await this.onUnauthorized?.("user_suspended");
|
||||
}
|
||||
|
||||
if (error.error === "csrf_error") {
|
||||
@@ -282,6 +314,14 @@ class ApiClient {
|
||||
throw err;
|
||||
};
|
||||
|
||||
/**
|
||||
* Performs a GET request against the API.
|
||||
*
|
||||
* @param path the request path, relative to the base URL or an absolute URL.
|
||||
* @param data the data serialized into the query string.
|
||||
* @param options additional request options.
|
||||
* @returns the parsed JSON response.
|
||||
*/
|
||||
// oxlint-disable-next-line no-explicit-any
|
||||
get = <T = any>(
|
||||
path: string,
|
||||
@@ -289,23 +329,68 @@ class ApiClient {
|
||||
options?: FetchOptions
|
||||
) => this.fetch<T>(path, "GET", data, options);
|
||||
|
||||
/**
|
||||
* Performs a POST request against the API. Identical in-flight requests are
|
||||
* deduplicated and share a single response, except for multipart uploads.
|
||||
*
|
||||
* @param path the request path, relative to the base URL or an absolute URL.
|
||||
* @param data the request payload, sent as a JSON or multipart body.
|
||||
* @param options additional request options.
|
||||
* @returns the parsed JSON response.
|
||||
*/
|
||||
// oxlint-disable-next-line no-explicit-any
|
||||
post = <T = any>(
|
||||
path: string,
|
||||
data?: JSONObject | FormData,
|
||||
options?: FetchOptions
|
||||
): Promise<T> => this.deduplicate<T>(path, "POST", data, options);
|
||||
|
||||
/**
|
||||
* Performs a PUT request against the API. Identical in-flight requests are
|
||||
* deduplicated and share a single response, except for multipart uploads.
|
||||
*
|
||||
* @param path the request path, relative to the base URL or an absolute URL.
|
||||
* @param data the request payload, sent as a JSON or multipart body.
|
||||
* @param options additional request options.
|
||||
* @returns the parsed JSON response.
|
||||
*/
|
||||
// oxlint-disable-next-line no-explicit-any
|
||||
put = <T = any>(
|
||||
path: string,
|
||||
data?: JSONObject | FormData,
|
||||
options?: FetchOptions
|
||||
): Promise<T> => this.deduplicate<T>(path, "PUT", data, options);
|
||||
|
||||
/**
|
||||
* Sends a request, deduplicating identical in-flight requests so concurrent
|
||||
* callers share a single response. Multipart uploads are never deduplicated.
|
||||
*
|
||||
* @param path the request path, relative to the base URL or an absolute URL.
|
||||
* @param method the HTTP method to use.
|
||||
* @param data the request payload.
|
||||
* @param options additional request options.
|
||||
* @returns the parsed JSON response.
|
||||
*/
|
||||
// oxlint-disable-next-line no-explicit-any
|
||||
private deduplicate = <T = any>(
|
||||
path: string,
|
||||
method: Method,
|
||||
data?: JSONObject | FormData,
|
||||
options?: FetchOptions
|
||||
): Promise<T> => {
|
||||
if (data instanceof FormData) {
|
||||
return this.fetch<T>(path, "POST", data, options);
|
||||
return this.fetch<T>(path, method, data, options);
|
||||
}
|
||||
|
||||
const key = `${path}:${JSON.stringify(data)}:${JSON.stringify(options)}`;
|
||||
const key = `${method}:${path}:${JSON.stringify(data)}:${JSON.stringify(
|
||||
options
|
||||
)}`;
|
||||
const inflight = this.inflightRequests.get(key);
|
||||
if (inflight) {
|
||||
return inflight;
|
||||
}
|
||||
|
||||
const promise = this.fetch<T>(path, "POST", data, options).finally(() => {
|
||||
const promise = this.fetch<T>(path, method, data, options).finally(() => {
|
||||
this.inflightRequests.delete(key);
|
||||
});
|
||||
this.inflightRequests.set(key, promise);
|
||||
@@ -313,4 +398,5 @@ class ApiClient {
|
||||
};
|
||||
}
|
||||
|
||||
/** Shared API client instance configured against the default base URL. */
|
||||
export const client = new ApiClient();
|
||||
@@ -2,6 +2,7 @@
|
||||
import { vi } from "vitest";
|
||||
|
||||
export const client = {
|
||||
setUnauthorizedHandler: vi.fn(),
|
||||
post: vi.fn(() =>
|
||||
Promise.resolve({
|
||||
data: {
|
||||
|
||||
Reference in new issue
Block a user