refactor: rename packages and files to use 'flash' prefix for consistency

2026-04-26 12:34:49 +02:00
parent 9e19f439be
commit 8a52c4f143
279 changed files with 2774 additions and 752 deletions
@@ -0,0 +1,24 @@
+# flash-web-bundler
+
+`flash-web-bundler` integrates frontend tooling lifecycle into Flash with explicit, policy-driven behavior.
+
+## Quick Start
+
+```java
+FlashApp.create(8080)
+    .install(new WebBundlerExtension(
+        WebBundlerConfig.builder()
+            .webRoot(Path.of("web"))
+            .basePath("/")
+            .build()
+    ))
+    .start();
+```
+
+## Operating Model
+
+- Dev: orchestrates frontend process lifecycle and health checks.
+- Prod: serves prebuilt assets from `assetsSource` with ETag/cache/compression support.
+- Route precedence: backend first, SPA fallback second (`GET`/`HEAD`).
+
+See also: `asset-sources.md`.
@@ -0,0 +1,22 @@
+# Asset Sources
+
+`flash-web-bundler` uses explicit source objects for production assets.
+
+Supported sources:
+
+- `FilesystemAssetsSource.of(Path)`
+- `ClasspathAssetsSource.of(String rootPrefix)`
+
+Builder shortcuts:
+
+- `.assetsFromFilesystem(Path.of("dist"))`
+- `.assetsFromClasspath("web/dist")`
+
+Classpath source requires `asset-manifest.json` generated at build time.
+The developer does not maintain this file manually.
+
+Production startup is fail-fast if:
+
+- manifest is missing
+- manifest is invalid
+- manifest points to missing resources
@@ -0,0 +1,30 @@
+# Configuration
+
+`WebBundlerConfig` is immutable and built with `WebBundlerConfig.builder()`.
+
+Key fields:
+
+- `runtimeMode`: `PROD`, `ENV`, `AUTODETECT`
+- `operationMode`: `ORCHESTRATE_ONLY`, `MANAGED`
+- `frontendType`: currently `VITE`
+- `packageManager`: `NPM`, `PNPM`, `YARN`, `BUN`
+- `installPolicy`: `AUTO_IF_LOCK_HASH_CHANGED`, `NEVER`
+- `loggingMode`: `MERGED`, `SEPARATE`, `QUIET`, `VERBOSE`
+- `commandSafetyMode`: `WARN`, `BLOCK`, `ALLOW`
+- `webRoot`, `assetsSource`, `basePath`, `devHost`, `devPort`, `watchList`
+
+Asset source is explicit and object-based:
+
+- `assetsFromFilesystem(Path.of("dist"))`
+- `assetsFromClasspath("web/dist")`
+
+Or by direct source object:
+
+- `assetsSource(FilesystemAssetsSource.of(Path.of("dist")))`
+- `assetsSource(ClasspathAssetsSource.of("web/dist"))`
+
+Validation is fail-fast:
+
+- invalid `devPort`
+- blank/invalid watch entries
+- invalid `basePath`
@@ -0,0 +1,16 @@
+# Dev Lifecycle
+
+Boot flow in dev mode:
+
+1. Resolve runtime mode.
+2. Validate configuration and command safety.
+3. Optionally install dependencies (hash-based lockfile cache).
+4. Start dev server process.
+5. Run healthcheck.
+6. Start watchlist loop and restart dev process when tracked files change.
+
+Failure conditions are fail-fast:
+
+- occupied dev port
+- command launch failure
+- healthcheck timeout
@@ -0,0 +1,12 @@
+# Frontend Selection
+
+Frontend integration is explicit through `frontendType`.
+
+- No heuristic detection in v1.
+- Deterministic mapping: `FrontendType -> FrontendStrategy`.
+- Current built-in strategy: `VITE`.
+
+Extension points:
+
+- register custom `FrontendStrategy` implementations in the resolver.
+- override default commands per config.
@@ -0,0 +1,12 @@
+# Modes
+
+## Runtime Mode
+
+- `PROD`: production static serving only.
+- `AUTODETECT`: uses `Flash.DEV`.
+- `ENV`: uses `FLASH_WEB_BUNDLER_MODE` (`dev` => dev mode, else prod).
+
+## Operation Mode
+
+- `ORCHESTRATE_ONLY`: only orchestrates dev tooling.
+- `MANAGED`: enables production serving + SPA fallback routes.
@@ -0,0 +1,19 @@
+# Package Managers
+
+Package manager selection is explicit via `packageManager`.
+
+- `NPM` -> `package-lock.json`
+- `PNPM` -> `pnpm-lock.yaml`
+- `YARN` -> `yarn.lock`
+- `BUN` -> `bun.lockb`
+
+Install policy:
+
+- `AUTO_IF_LOCK_HASH_CHANGED`: install only when lock hash changes.
+- `NEVER`: never auto-install.
+
+Custom commands can override defaults via:
+
+- `installCommand`
+- `devCommand`
+- `buildCommand`
@@ -0,0 +1,13 @@
+# Performance Notes
+
+Current v1 optimizations:
+
+- startup preloading of static assets
+- precomputed ETags and MIME lookup
+- compressed payload selection based on `Accept-Encoding`
+- lockfile-hash install gate to avoid redundant installs
+
+Future performance work:
+
+- streaming/sliced file serving for large assets
+- benchmark suite with p50/p95/p99 latency and allocation profiling
@@ -0,0 +1,17 @@
+# Production Serving
+
+In production mode, `flash-web-bundler` serves only prebuilt assets.
+
+Behavior:
+
+- preloads files from `assetsSource` (filesystem or classpath)
+- resolves MIME by extension
+- supports precompressed siblings (`.br`, `.gz`)
+- sets `Cache-Control` and `ETag`
+- responds `304 Not Modified` when `If-None-Match` matches
+
+Classpath mode details:
+
+- reads entries from `asset-manifest.json` in classpath root
+- validates referenced resources at startup
+- fails fast in production if manifest or resources are inconsistent
@@ -0,0 +1,10 @@
+# Routing Fallback
+
+Fallback policy:
+
+- backend routes always have precedence
+- fallback route is wildcard under configured `basePath`
+- fallback applies to `GET` and `HEAD` only
+- if no static asset matches, serve SPA `indexFile`
+
+Namespace collisions should be avoided at app design level (for example, keep API under `/api`).
@@ -0,0 +1,11 @@
+# Security Policies
+
+Command safety is enforced before process execution.
+
+Modes:
+
+- `WARN`: allow unknown binary and log warning.
+- `BLOCK`: reject unknown binary.
+- `ALLOW`: skip safe-registry checks.
+
+Safe registry defaults include common package-manager executables and is configurable.