Compare commits

..
Author SHA1 Message Date
Anthony Stirling 5dc0c79057 Scope frontend load balancer to proprietary UI 2025-11-16 23:05:51 +00:00
15 changed files with 293 additions and 114 deletions
@@ -1,37 +0,0 @@
package stirling.software.common.annotations.api;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import io.swagger.v3.oas.annotations.tags.Tag;
/**
* Combined annotation for Invite management controllers.
* Includes @RestController, @RequestMapping("/api/v1/invite"), and OpenAPI @Tag.
*/
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@RestController
@RequestMapping("/api/v1/invite")
@Tag(
name = "Invite",
description =
"""
Invite-link generation and acceptance endpoints for onboarding new users.
Provides the ability to issue invitation tokens, send optional email invites,
validate and accept invite links, and manage pending invitations for teams.
Typical use cases include:
• Admin workflows for issuing time-limited invitations to external users
• Self-service invite acceptance and team assignment
• License limit enforcement when provisioning new accounts
Target users: administrators and automation scripts orchestrating user onboarding.
""")
public @interface InviteApi {}
@@ -129,53 +129,61 @@ public class SecurityConfiguration {
@Bean
public CorsConfigurationSource corsConfigurationSource() {
List<String> configuredOrigins = null;
if (applicationProperties.getSystem() != null) {
configuredOrigins = applicationProperties.getSystem().getCorsAllowedOrigins();
}
// Read CORS allowed origins from settings
if (applicationProperties.getSystem() != null
&& applicationProperties.getSystem().getCorsAllowedOrigins() != null
&& !applicationProperties.getSystem().getCorsAllowedOrigins().isEmpty()) {
CorsConfiguration cfg = new CorsConfiguration();
if (configuredOrigins != null && !configuredOrigins.isEmpty()) {
cfg.setAllowedOriginPatterns(configuredOrigins);
List<String> allowedOrigins = applicationProperties.getSystem().getCorsAllowedOrigins();
CorsConfiguration cfg = new CorsConfiguration();
// Use setAllowedOriginPatterns for better wildcard and port support
cfg.setAllowedOriginPatterns(allowedOrigins);
log.debug(
"CORS configured with allowed origin patterns from settings.yml: {}",
configuredOrigins);
allowedOrigins);
// Set allowed methods explicitly (including OPTIONS for preflight)
cfg.setAllowedMethods(List.of("GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"));
// Set allowed headers explicitly
cfg.setAllowedHeaders(
List.of(
"Authorization",
"Content-Type",
"X-Requested-With",
"Accept",
"Origin",
"X-API-KEY",
"X-CSRF-TOKEN"));
// Set exposed headers (headers that the browser can access)
cfg.setExposedHeaders(
List.of(
"WWW-Authenticate",
"X-Total-Count",
"X-Page-Number",
"X-Page-Size",
"Content-Disposition",
"Content-Type"));
// Allow credentials (cookies, authorization headers)
cfg.setAllowCredentials(true);
// Set max age for preflight cache
cfg.setMaxAge(3600L);
UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
source.registerCorsConfiguration("/**", cfg);
return source;
} else {
// Default to allowing all origins when nothing is configured
cfg.setAllowedOriginPatterns(List.of("*"));
// No CORS origins configured - return null to disable CORS processing entirely
// This avoids empty CORS policy that unexpectedly rejects preflights
log.info(
"No CORS allowed origins configured in settings.yml (system.corsAllowedOrigins); allowing all origins.");
"CORS is disabled - no allowed origins configured in settings.yml (system.corsAllowedOrigins)");
return null;
}
// Explicitly configure supported HTTP methods (include OPTIONS for preflight)
cfg.setAllowedMethods(List.of("GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"));
cfg.setAllowedHeaders(
List.of(
"Authorization",
"Content-Type",
"X-Requested-With",
"Accept",
"Origin",
"X-API-KEY",
"X-CSRF-TOKEN",
"X-XSRF-TOKEN"));
cfg.setExposedHeaders(
List.of(
"WWW-Authenticate",
"X-Total-Count",
"X-Page-Number",
"X-Page-Size",
"Content-Disposition",
"Content-Type"));
cfg.setAllowCredentials(true);
cfg.setMaxAge(3600L);
UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
source.registerCorsConfiguration("/**", cfg);
return source;
}
@Bean
@@ -15,7 +15,7 @@ import jakarta.servlet.http.HttpServletRequest;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import stirling.software.common.annotations.api.InviteApi;
import stirling.software.common.annotations.api.UserApi;
import stirling.software.common.model.ApplicationProperties;
import stirling.software.common.model.enumeration.Role;
import stirling.software.proprietary.model.Team;
@@ -26,9 +26,11 @@ import stirling.software.proprietary.security.service.EmailService;
import stirling.software.proprietary.security.service.TeamService;
import stirling.software.proprietary.security.service.UserService;
@InviteApi
@UserApi
@Slf4j
@RequiredArgsConstructor
@RestController
@RequestMapping("/api/v1/invite")
public class InviteLinkController {
private final InviteTokenRepository inviteTokenRepository;
+1
View File
@@ -47,6 +47,7 @@ docker-compose -f docker/compose/docker-compose.fat.yml up --build
## Configuration
- **Backend URL**: Set `VITE_API_BASE_URL` environment variable for custom backend locations
- **Load-balanced backends**: Provide a comma-separated list via `VITE_API_BASE_URLS` (for example `https://api-1.example.com,https://api-2.example.com`) to let the web client distribute requests across multiple backend nodes without an external proxy
- **Custom Ports**: Modify port mappings in docker-compose files
- **Memory Limits**: Adjust memory limits per variant (2G ultra-lite, 4G standard, 6G fat)
+5
View File
@@ -108,6 +108,7 @@ Swagger UI at: `http://localhost:8080/swagger-ui/index.html`
| Variable | Default | Description |
|----------|---------|-------------|
| `VITE_API_BASE_URL` | `http://backend:8080` | Backend URL for API proxying |
| `VITE_API_BASE_URLS` | _(empty)_ | Optional comma-separated list of backend URLs for the React client to load balance across (requires the browser to reach those URLs directly) |
### Standard Configuration
@@ -269,6 +270,10 @@ docker build \
MODE: FRONTEND
VITE_API_BASE_URL: http://load-balancer:8080
```
You can also skip the external load balancer for browser clients by defining
`VITE_API_BASE_URLS` with a comma-separated list of backend URLs. The
Stirling-PDF frontend will round-robin requests across the provided hosts and
temporarily avoid nodes that return network errors/5xx responses.
---
-1
View File
@@ -7,7 +7,6 @@ import { getApiBaseUrl } from '@app/services/apiClientConfig';
const apiClient = axios.create({
baseURL: getApiBaseUrl(),
responseType: 'json',
withCredentials: true,
});
// Setup interceptors (core does nothing, proprietary adds JWT auth)
@@ -4,6 +4,7 @@ import { useTranslation } from 'react-i18next';
import apiClient from '@app/services/apiClient';
import { tauriBackendService } from '@app/services/tauriBackendService';
import { isBackendNotReadyError } from '@app/constants/backendErrors';
import { parseBackendUrlList } from '@proprietary/services/backendBalancer';
interface EndpointConfig {
backendUrl: string;
@@ -241,10 +242,12 @@ export function useMultipleEndpointsEnabled(endpoints: string[]): {
export function useEndpointConfig(): EndpointConfig {
const backendUrl = useMemo(() => {
const runtimeEnv = typeof process !== 'undefined' ? process.env : undefined;
const apiBaseCandidates = parseBackendUrlList(import.meta.env.VITE_API_BASE_URLS);
const firstConfiguredBase = apiBaseCandidates[0] || import.meta.env.VITE_API_BASE_URL;
return runtimeEnv?.STIRLING_BACKEND_URL
|| import.meta.env.VITE_DESKTOP_BACKEND_URL
|| import.meta.env.VITE_API_BASE_URL
|| firstConfiguredBase
|| 'http://localhost:8080';
}, []);
@@ -1,17 +1,40 @@
import { isTauri } from '@tauri-apps/api/core';
import {
createBackendBalancer,
resolveConfiguredBackendUrls,
type BackendBalancer,
type BackendBalancerStrategy,
} from '@proprietary/services/backendBalancer';
const configuredUrls = resolveConfiguredBackendUrls(import.meta.env);
const strategy = (import.meta.env.VITE_API_BACKEND_STRATEGY as BackendBalancerStrategy | undefined) || 'round-robin';
const cooldownEnv = Number.parseInt(import.meta.env.VITE_API_BACKEND_FAILURE_COOLDOWN_MS ?? '', 10);
const failureCooldownMs = Number.isFinite(cooldownEnv) ? cooldownEnv : undefined;
const backendBalancer: BackendBalancer = createBackendBalancer(configuredUrls, {
strategy,
failureCooldownMs,
});
function getTauriBaseUrl(): string {
if (import.meta.env.DEV) {
return '/';
}
return import.meta.env.VITE_DESKTOP_BACKEND_URL || 'http://localhost:8080';
}
/**
* Desktop override: Determine base URL depending on Tauri environment
*/
export function getApiBaseUrl(): string {
if (!isTauri()) {
return import.meta.env.VITE_API_BASE_URL || '/';
return backendBalancer.getNextBaseUrl();
}
return getTauriBaseUrl();
}
export function reportBackendFailure(baseUrl?: string | null): void {
if (!isTauri()) {
backendBalancer.reportFailure(baseUrl ?? undefined);
}
if (import.meta.env.DEV) {
// During tauri dev we rely on Vite proxy, so use relative path to avoid CORS preflight
return '/';
}
return import.meta.env.VITE_DESKTOP_BACKEND_URL || 'http://localhost:8080';
}
@@ -107,7 +107,7 @@ class SpringAuthClient {
for (const cookie of cookies) {
const [name, value] = cookie.trim().split('=');
if (name === 'XSRF-TOKEN') {
return decodeURIComponent(value);
return value;
}
}
return null;
@@ -278,7 +278,7 @@ class SpringAuthClient {
try {
const response = await apiClient.post('/api/v1/auth/logout', null, {
headers: {
'X-XSRF-TOKEN': this.getCsrfToken() || '',
'X-CSRF-TOKEN': this.getCsrfToken() || '',
},
withCredentials: true,
});
@@ -311,7 +311,7 @@ class SpringAuthClient {
try {
const response = await apiClient.post('/api/v1/auth/refresh', null, {
headers: {
'X-XSRF-TOKEN': this.getCsrfToken() || '',
'X-CSRF-TOKEN': this.getCsrfToken() || '',
},
withCredentials: true,
});
@@ -0,0 +1,39 @@
import axios from 'axios';
import { handleHttpError } from '@app/services/httpErrorHandler';
import { setupApiInterceptors } from '@app/services/apiClientSetup';
import { getApiBaseUrl, reportBackendFailure } from '@app/services/apiClientConfig';
// Create axios instance with default config
const apiClient = axios.create({
responseType: 'json',
});
apiClient.interceptors.request.use((config) => {
if (!config.baseURL) {
config.baseURL = getApiBaseUrl();
}
return config;
});
// Setup interceptors (core does nothing, proprietary adds JWT auth)
setupApiInterceptors(apiClient);
// ---------- Install error interceptor ----------
apiClient.interceptors.response.use(
(response) => response,
async (error) => {
if (axios.isAxiosError(error)) {
const status = error.response?.status;
const isServerOrNetworkFailure = !status || status >= 500;
if (isServerOrNetworkFailure) {
reportBackendFailure(error.config?.baseURL);
}
}
await handleHttpError(error); // Handle error (shows toast unless suppressed)
return Promise.reject(error);
}
);
// ---------- Exports ----------
export default apiClient;
@@ -0,0 +1,30 @@
import {
createBackendBalancer,
resolveConfiguredBackendUrls,
type BackendBalancer,
type BackendBalancerStrategy,
} from '@proprietary/services/backendBalancer';
const configuredUrls = resolveConfiguredBackendUrls(import.meta.env);
const strategy = (import.meta.env.VITE_API_BACKEND_STRATEGY as BackendBalancerStrategy | undefined) || 'round-robin';
const cooldownEnv = Number.parseInt(import.meta.env.VITE_API_BACKEND_FAILURE_COOLDOWN_MS ?? '', 10);
const failureCooldownMs = Number.isFinite(cooldownEnv) ? cooldownEnv : undefined;
const backendBalancer: BackendBalancer = createBackendBalancer(configuredUrls, {
strategy,
failureCooldownMs,
});
/**
* Select the next backend base URL using the configured strategy.
*/
export function getApiBaseUrl(): string {
return backendBalancer.getNextBaseUrl();
}
/**
* Notify the balancer that a backend failed so it can be temporarily deprioritized.
*/
export function reportBackendFailure(baseUrl?: string | null): void {
backendBalancer.reportFailure(baseUrl ?? undefined);
}
@@ -9,38 +9,17 @@ function getJwtTokenFromStorage(): string | null {
}
}
function getXsrfToken(): string | null {
try {
const cookies = document.cookie.split(';');
for (const cookie of cookies) {
const [name, value] = cookie.trim().split('=');
if (name === 'XSRF-TOKEN') {
return decodeURIComponent(value);
}
}
return null;
} catch (error) {
console.error('[API Client] Failed to read XSRF token from cookies:', error);
return null;
}
}
export function setupApiInterceptors(client: AxiosInstance): void {
// Install request interceptor to add JWT token
client.interceptors.request.use(
(config) => {
const jwtToken = getJwtTokenFromStorage();
const xsrfToken = getXsrfToken();
if (jwtToken && !config.headers.Authorization) {
config.headers.Authorization = `Bearer ${jwtToken}`;
console.debug('[API Client] Added JWT token from localStorage to Authorization header');
}
if (xsrfToken && !config.headers['X-XSRF-TOKEN']) {
config.headers['X-XSRF-TOKEN'] = xsrfToken;
}
return config;
},
(error) => {
@@ -0,0 +1,119 @@
export type BackendBalancerStrategy = 'round-robin' | 'random';
export interface BackendBalancerOptions {
strategy?: BackendBalancerStrategy;
failureCooldownMs?: number;
}
export interface BackendBalancer {
getNextBaseUrl(): string;
getAllBaseUrls(): string[];
reportFailure(baseUrl?: string | null): void;
}
const DEFAULT_BASE_URL = '/';
const DEFAULT_COOLDOWN_MS = 15000;
export function sanitizeBaseUrl(raw: string): string {
const trimmed = raw.trim();
if (!trimmed) return '';
if (trimmed === '/') return '/';
return trimmed.replace(/\/+$/, '');
}
export function parseBackendUrlList(raw?: string | string[] | null): string[] {
if (!raw) return [];
const parts = Array.isArray(raw)
? raw
: raw
.split(/[,\s]+/)
.map((segment) => segment.trim())
.filter(Boolean);
const normalized: string[] = [];
for (const candidate of parts) {
const sanitized = sanitizeBaseUrl(candidate);
if (sanitized && !normalized.includes(sanitized)) {
normalized.push(sanitized);
}
}
return normalized;
}
interface EnvLike {
[key: string]: string | undefined;
}
export function resolveConfiguredBackendUrls(
env?: EnvLike,
fallback: string = DEFAULT_BASE_URL
): string[] {
const rawMulti = env?.VITE_API_BASE_URLS;
const rawSingle = env?.VITE_API_BASE_URL;
const parsed = [rawMulti, rawSingle]
.flatMap((value) => parseBackendUrlList(value))
.filter(Boolean);
if (parsed.length > 0) {
return parsed;
}
const sanitizedFallback = sanitizeBaseUrl(fallback);
return sanitizedFallback ? [sanitizedFallback] : [DEFAULT_BASE_URL];
}
export function createBackendBalancer(
urls: string[],
options?: BackendBalancerOptions
): BackendBalancer {
const unique = urls.length > 0 ? Array.from(new Set(urls.map(sanitizeBaseUrl).filter(Boolean))) : [DEFAULT_BASE_URL];
let pointer = 0;
const penalties = new Map<string, number>();
const strategy: BackendBalancerStrategy = options?.strategy ?? 'round-robin';
const cooldown = Math.max(0, options?.failureCooldownMs ?? DEFAULT_COOLDOWN_MS);
function getCandidateRoundRobin(now: number): string {
for (let attempt = 0; attempt < unique.length; attempt += 1) {
const idx = (pointer + attempt) % unique.length;
const candidate = unique[idx];
const penaltyExpires = penalties.get(candidate) ?? 0;
if (penaltyExpires <= now) {
pointer = (idx + 1) % unique.length;
return candidate;
}
}
pointer = (pointer + 1) % unique.length;
return unique[pointer];
}
function getCandidateRandom(now: number): string {
for (let attempt = 0; attempt < unique.length; attempt += 1) {
const idx = Math.floor(Math.random() * unique.length);
const candidate = unique[idx];
const penaltyExpires = penalties.get(candidate) ?? 0;
if (penaltyExpires <= now) {
return candidate;
}
}
return unique[Math.floor(Math.random() * unique.length)];
}
function pickCandidate(): string {
const now = Date.now();
return strategy === 'random' ? getCandidateRandom(now) : getCandidateRoundRobin(now);
}
function reportFailure(baseUrl?: string | null): void {
if (!baseUrl) return;
const normalized = sanitizeBaseUrl(baseUrl);
if (!normalized) return;
const expiresAt = Date.now() + cooldown;
penalties.set(normalized, expiresAt);
}
return {
getNextBaseUrl: pickCandidate,
getAllBaseUrls: () => [...unique],
reportFailure,
};
}
+3
View File
@@ -4,6 +4,9 @@
"paths": {
"@app/*": [
"src/core/*"
],
"@core/*": [
"src/core/*"
]
}
},
+5
View File
@@ -3,6 +3,11 @@
interface ImportMetaEnv {
readonly VITE_PUBLIC_POSTHOG_KEY: string;
readonly VITE_PUBLIC_POSTHOG_HOST: string;
readonly VITE_API_BASE_URL?: string;
readonly VITE_API_BASE_URLS?: string;
readonly VITE_API_BACKEND_STRATEGY?: 'round-robin' | 'random';
readonly VITE_API_BACKEND_FAILURE_COOLDOWN_MS?: string;
readonly VITE_DESKTOP_BACKEND_URL?: string;
}
interface ImportMeta {