sessions.go

Overview

The sessions.go file defines the SessionsAPIRouter struct and its associated methods to set up HTTP routing for session-related REST API endpoints. It acts as a liaison between incoming HTTP requests targeting session management operations and the corresponding controller handlers implemented in the SessionsAPIController. This router encapsulates the route declarations for session CRUD (Create, Read, Delete) operations, including listing sessions and creating sessions either with or without an explicit session ID.

The file contributes to the modular routing infrastructure described in Router Setup and supports session lifecycle management as part of the REST API layer outlined in REST API and Web Launchers.

Structure and Components

SessionsAPIRouter

type SessionsAPIRouter struct {
	sessionController *controllers.SessionsAPIController
}

• Purpose:
  Encapsulates routing logic for all session-related endpoints. Holds a reference to a SessionsAPIController instance responsible for executing the business logic behind each route.

• Fields:

  • sessionController: A pointer to SessionsAPIController which implements the HTTP handler functions for session management.

NewSessionsAPIRouter

func NewSessionsAPIRouter(controller *controllers.SessionsAPIController) *SessionsAPIRouter {
	return &SessionsAPIRouter{sessionController: controller}
}

• Purpose:
  Factory function to create a new SessionsAPIRouter instance with the specified SessionsAPIController.

• Parameters:

  • controller: A pointer to an existing SessionsAPIController.

• Returns:

  • A pointer to a new SessionsAPIRouter initialized with the provided controller.

• Usage Example:

  controller := controllers.NewSessionsAPIController(sessionService)
  router := NewSessionsAPIRouter(controller)
  

Routes Method

func (r *SessionsAPIRouter) Routes() Routes

• Purpose:
  Returns a slice of Route structs defining the HTTP endpoints handled by the sessions router.

• Returns:

  • Routes: A slice containing route definitions, each specifying:

    • Name: Unique identifier for the route.

    • Methods: HTTP methods supported (e.g., GET, POST, DELETE).

    • Pattern: URL path pattern with path variables.

    • HandlerFunc: The HTTP handler function from the sessions controller.

• Defined Routes:

  Route Name	HTTP Methods	URL Pattern	Handler Function
  GetSession	GET	/apps/{app_name}/users/{user_id}/sessions/{session_id}	GetSessionHandler
  CreateSession	POST	/apps/{app_name}/users/{user_id}/sessions	CreateSessionHandler
  CreateSessionWithId	POST	/apps/{app_name}/users/{user_id}/sessions/{session_id}	CreateSessionHandler
  DeleteSession	DELETE, OPTIONS	/apps/{app_name}/users/{user_id}/sessions/{session_id}	DeleteSessionHandler
  ListSessions	GET	/apps/{app_name}/users/{user_id}/sessions	ListSessionsHandler

• Notes on Routes:

  • The CreateSession and CreateSessionWithId routes both use the CreateSessionHandler. The latter allows clients to specify a session ID explicitly.

  • The DeleteSession route supports both DELETE method for deleting a session and OPTIONS method for CORS preflight requests.

  • URL path variables ({app_name}, {user_id}, {session_id}) allow dynamic routing based on application, user, and session identifiers.

Interaction with Other Components

• SessionsAPIController (from controllers package):
  The SessionsAPIRouter depends on SessionsAPIController to handle the actual HTTP requests. Each route delegates to a corresponding handler method in the controller, which implements session lifecycle logic such as creating, retrieving, listing, and deleting sessions.

• Routing Infrastructure (Router Setup):
  The router integrates into the larger HTTP server routing system by providing its routes to a multiplexer (e.g., mux.Router). This modular approach allows the server to compose multiple routers (runtime, artifacts, apps, debug) into a single cohesive API.

• Session Management (Session Management):
  The controller behind these routes interacts with the session management service layer responsible for persisting session state, managing event history, and retrieval operations.

• REST API Server (REST API and Web Launchers):
  This router contributes to the REST API server serving session management endpoints under the /apps/{app_name}/users/{user_id}/sessions path namespace.

Implementation Details and Algorithms

• Routing Patterns:
  Uses path variables in the route patterns to capture hierarchical resource identifiers (app_name, user_id, session_id). This design follows RESTful API conventions for resource scoping.

• HTTP Methods and Idempotency:

  • GET methods are used for read operations (GetSession, ListSessions).

  • POST is used for creating sessions, with or without specifying a session ID.

  • DELETE is used for session removal.

  • OPTIONS method support for CORS preflight on the DeleteSession route.

• Controller Delegation:
  The router does not implement business logic internally. Instead, it acts as a declarative mapping between HTTP routes and controller handler functions, centralizing route definitions and enabling the controller to focus on request processing and response generation.

Usage Example

Assuming a SessionsAPIController instance has been created, the router can be instantiated and integrated into the HTTP server setup:

import (
	"net/http"
	"google.golang.org/adk/server/adkrest/controllers"
	"google.golang.org/adk/server/adkrest/internal/routers"
)

func main() {
	sessionController := controllers.NewSessionsAPIController(sessionService)
	sessionsRouter := routers.NewSessionsAPIRouter(sessionController)

	routes := sessionsRouter.Routes()
	mainMux := http.NewServeMux()

	for _, route := range routes {
		mainMux.HandleFunc(route.Pattern, route.HandlerFunc)
	}

	http.ListenAndServe(":8080", mainMux)
}

This example demonstrates how SessionsAPIRouter provides the route definitions and handlers which can then be registered with the HTTP multiplexer.

Visual Diagram

classDiagram
class SessionsAPIRouter {
-sessionController: SessionsAPIController
+NewSessionsAPIRouter()
+Routes()
}
class SessionsAPIController {
+GetSessionHandler()
+CreateSessionHandler()
+DeleteSessionHandler()
+ListSessionsHandler()
}
SessionsAPIRouter "1" *-- "1" SessionsAPIController
SessionsAPIRouter : Routes() --> Route
class Route {
+Name
+Methods
+Pattern
+HandlerFunc
}
SessionsAPIRouter ..> Route : returns

• Explanation:
  The SessionsAPIRouter maintains a reference to the SessionsAPIController, delegating HTTP route handling to it. The Routes() method returns a collection of Route objects specifying the REST API endpoints related to sessions.

Summary of Routes and Their Handlers

These routes provide full CRUD capabilities on session resources scoped by application and user.

This file is a core component of the session management REST API routing, enabling modular and maintainable HTTP endpoint definitions, which integrate tightly with session lifecycle controllers and the broader REST API server infrastructure.