Router Setup

Purpose

The Router Setup subtopic addresses the organization and definition of API routers and their associated routes for the REST endpoints exposed by the system. It serves as the foundational layer that maps incoming HTTP requests to their corresponding handlers, which are implemented as controllers within the broader REST API server infrastructure described in the parent topic REST API and Web Launchers. This setup is essential for enabling structured, maintainable, and scalable HTTP routing using the popular gorilla/mux package in Go.

While the parent topic outlines the overall REST API server and web launcher functionalities, Router Setup specifically focuses on how the routing layer is constructed and integrated, defining the modular routers and their RESTful endpoint patterns. This subtopic ensures that different API domains such as runtime execution, session management, artifact handling, applications, and debugging are cleanly separated and routed to their respective controllers.

Functionality

The core functionality of the Router Setup involves:

• Defining Router Types: Each API domain has a dedicated router struct (e.g., RuntimeAPIRouter, SessionsAPIRouter, ArtifactsAPIRouter) that encapsulates a controller instance responsible for handling requests under that domain.

• Route Declaration: Each router implements a Routes() method returning a list of Route definitions. Each Route specifies:

  • A unique name for identification.

  • Supported HTTP methods (e.g., GET, POST, DELETE).

  • A URL pattern with path variables (e.g., /apps/{app_name}/users/{user_id}/sessions/{session_id}).

  • The HTTP handler function, typically wrapped with error handling middleware.

• Router Aggregation: The NewRouter function (in routers.go) creates a top-level mux.Router instance and populates it by aggregating routes from all individual routers via SetupSubRouters. This modular approach allows easy extension and maintenance of the API surface.

• Request Handling: When an HTTP request arrives, gorilla/mux matches the request's method and URL path against the registered routes and dispatches it to the appropriate handler function defined in the controllers (e.g., RuntimeAPIController.RunHandler).

This subtopic organizes routes by API concern, for example:

• RuntimeAPIRouter handles /run and /run_sse POST endpoints to invoke agent execution.

• SessionsAPIRouter manages session CRUD endpoints under /apps/{app_name}/users/{user_id}/sessions.

• ArtifactsAPIRouter defines routes for artifact listing, loading, and deletion scoped to sessions.

• AppsAPIRouter exposes application listing.

• DebugAPIRouter provides debugging routes such as trace retrieval.

The use of gorilla/mux enables expressive route patterns with variable extraction, method-based routing, and middleware chaining.

Key Code Snippet

Excerpt from runtime.go demonstrates the pattern of route definition for the runtime API router:

func (r *RuntimeAPIRouter) Routes() Routes {
	return Routes{
		Route{
			Name:        "RunAgent",
			Methods:     []string{http.MethodPost, http.MethodOptions},
			Pattern:     "/run",
			HandlerFunc: controllers.NewErrorHandler(r.runtimeController.RunHandler),
		},
		Route{
			Name:        "RunAgentSse",
			Methods:     []string{http.MethodPost, http.MethodOptions},
			Pattern:     "/run_sse",
			HandlerFunc: controllers.NewErrorHandler(r.runtimeController.RunSSEHandler),
		},
	}
}

Here, two POST endpoints /run and /run_sse are declared with handlers wrapped in a generic error handler. Similar patterns are used for other routers, each encapsulating their domain logic.

Integration

The Router Setup acts as the glue between HTTP requests and the internal REST API controllers described in the sibling subtopic REST API Controllers. Each router binds to a specific controller responsible for implementing the business logic of the API endpoints.

This setup complements other subtopics under REST API and Web Launchers by:

• Providing a clean, modular routing architecture that supports the addition of new API domains or endpoints without affecting existing routes.

• Enabling consistent error handling and middleware application across all API endpoints.

• Allowing the web UI launcher and CLI launcher components to interact with a well-structured REST API.

• Supporting session state management, artifact operations, and runtime agent invocation by linking HTTP endpoints to their respective controllers.

The routing definitions ensure that incoming API calls reach the correct handler methods, which in turn rely on services like session management (Session Management), artifact storage (Artifact Management), and agent execution (Agent Execution Runner) to fulfill requests.

Diagram

classDiagram
class Route {
+string Name
+[]string Methods
+string Pattern
+http.HandlerFunc HandlerFunc
}
class Router {
+Routes() Routes
}
class RuntimeAPIRouter {
-RuntimeAPIController runtimeController
+Routes() Routes
}
class SessionsAPIRouter {
-SessionsAPIController sessionController
+Routes() Routes
}
class ArtifactsAPIRouter {
-ArtifactsAPIController artifactsController
+Routes() Routes
}
class AppsAPIRouter {
-AppsAPIController appsController
+Routes() Routes
}
class DebugAPIRouter {
-DebugAPIController debugController
+Routes() Routes
}
class mux.Router
Router <|-- RuntimeAPIRouter
Router <|-- SessionsAPIRouter
Router <|-- ArtifactsAPIRouter
Router <|-- AppsAPIRouter
Router <|-- DebugAPIRouter
RuntimeAPIRouter "1" *-- "1" RuntimeAPIController
SessionsAPIRouter "1" *-- "1" SessionsAPIController
ArtifactsAPIRouter "1" *-- "1" ArtifactsAPIController
AppsAPIRouter "1" *-- "1" AppsAPIController
DebugAPIRouter "1" *-- "1" DebugAPIController
NewRouter o-- mux.Router : creates
mux.Router o-- Route : contains

This class diagram illustrates the structure of routers as types implementing a common interface, each holding a controller instance and defining their route sets. The top-level mux.Router aggregates these routes into a unified HTTP router used by the REST API server.