Package dev.relism.flash.extension

Class FlashApp

java.lang.Object
dev.relism.flash.extension.FlashRegistrar<FlashApp>
dev.relism.flash.extension.FlashApp
public final class FlashApp extends FlashRegistrar<FlashApp>
Single entry point for Flash. Owns one flat FastPathRouterImpl — all routes (app-level and scoped) compile into a single FSM at startup. 

 FlashApp.create(8080)
     .install(new JacksonExtension())
     .use(cors)
     .get("/ping",    (req, res) -> "pong")
     .get("/secured", (req, res) -> user(), oidc.protect())
     .scan("dev.example.handlers")
     .mount("/api", scope -> scope.get("/health", (req, res) -> "ok"))
     .startAndBlock();   // blocks main thread

Startup sequence (both start() and startAndBlock())

  1. All FlashExtension.configure(dev.relism.flash.extension.FlashRegistrar<?>, dev.relism.flash.extension.FlashContext) declarations.
  2. FlashContext.resolveAll() — topo-sort, cycle detection.
  3. Ready callbacks register routes with resolved services.
  4. Compile all routes into one flat FSM — zero prefix scanning at runtime.
  5. Accept loop started.

Default error handlers

Dev mode (-Dflash.env=dev): rich HTML with stack traces. Prod mode (default): generic JSON — no internal details leaked. Override via onException(dev.relism.flash.routing.AbstractRouter.ExceptionHandler) / onNotFound(dev.relism.flash.models.SimpleHandler.FunctionalHandler).

  • Method Details

    • create

      public static FlashApp create(int port)

    • create

      public static FlashApp create(FlashConfiguration cfg)

    • mount

      public FlashApp mount(String namespace, Consumer<FlashScope> configure)
      Mounts a scoped group of routes under namespace. Routes accumulate in a FlashScope builder and merge into this app's single flat router at startup — pure syntactic sugar, no extra router involved.

    • ws

      public FlashApp ws(String path, WebSocketHandler handler)
      Registers a WebSocket endpoint at path. Runs on the same virtual-thread model as HTTP handlers. A path may have both an HTTP handler and a WS endpoint simultaneously.

    • onException

      public FlashApp onException(AbstractRouter.ExceptionHandler handler)

    • onNotFound

      public FlashApp onNotFound(SimpleHandler.FunctionalHandler handler)

    • ctx

      public FlashContext ctx()
      Description copied from class: FlashRegistrar
      Returns the FlashContext for this registrar.
      Specified by:
      ctx in class FlashRegistrar<FlashApp>

    • install

      public FlashApp install(FlashExtension ext)
      Registers a declarative extension contribution.

    • apply

      public FlashApp apply(FlashApplication application)
      Applies a FlashApplication to this app. Runs immediately, so configure sees a context that is still open for declarations and a listener that is already bound (port()).

    • start

      public FlashApp start()
      Boots the server and starts accepting connections. Returns immediately — the accept loop runs on a background platform thread.

      Use startAndBlock() in main() if you have no other work to do after startup.

      Returns:
      this for storing or chaining (e.g. .start().ctx().require(...))

    • startAndBlock

      public void startAndBlock()
      Boots the server and blocks the calling thread until the server is stopped. Suitable for the end of main() — no need to keep the JVM alive manually.

    • stop

      public CompletableFuture<Void> stop()
      Gracefully stops the server, then runs every FlashContext.onClose(java.lang.Runnable) callback so services release what they hold. Draining first means in-flight requests still see a live service graph.

    • port

      public int port()
      Port of the first bound listener. Usable before start(): listeners bind when the app is created, so FlashApp.create(cfg with port 0).port() yields the OS-assigned port, and an app can even be configured against its own address.

    • ports

      public List<Integer> ports()
      Ports of every bound listener, in configuration order.

    • addRoute

      protected void addRoute(HttpMethod method, String path, RequestHandler handler, List<MiddlewareNode> mw)
      Description copied from class: FlashRegistrar
      Adds a route immediately to this registrar's deferred compilation list. Subclasses may prepend a namespace prefix and inject scope middlewares before storing.
      Specified by:
      addRoute in class FlashRegistrar<FlashApp>

    • addWsRoute

      protected void addWsRoute(String path, WebSocketEndpoint endpoint)
      Specified by:
      addWsRoute in class FlashRegistrar<FlashApp>

    • addMiddleware

      protected void addMiddleware(MiddlewareNode mw)
      Description copied from class: FlashRegistrar
      Registers a middleware in this registrar's own scope (global or scope-level).
      Specified by:
      addMiddleware in class FlashRegistrar<FlashApp>