Refactor codebase

internal/auth/claude/oauth_server.go

@@ -1,3 +1,6 @@
+// Package claude provides authentication and token management functionality
+// for Anthropic's Claude AI services. It handles OAuth2 token storage, serialization,
+// and retrieval for maintaining authenticated sessions with the Claude API.
 package claude
 
 import (
@@ -13,24 +16,45 @@ import (
 	log "github.com/sirupsen/logrus"
 )
 
-// OAuthServer handles the local HTTP server for OAuth callbacks
+// OAuthServer handles the local HTTP server for OAuth callbacks.
+// It listens for the authorization code response from the OAuth provider
+// and captures the necessary parameters to complete the authentication flow.
 type OAuthServer struct {
-	server     *http.Server
-	port       int
+	// server is the underlying HTTP server instance
+	server *http.Server
+	// port is the port number on which the server listens
+	port int
+	// resultChan is a channel for sending OAuth results
 	resultChan chan *OAuthResult
-	errorChan  chan error
-	mu         sync.Mutex
-	running    bool
+	// errorChan is a channel for sending OAuth errors
+	errorChan chan error
+	// mu is a mutex for protecting server state
+	mu sync.Mutex
+	// running indicates whether the server is currently running
+	running bool
 }
 
-// OAuthResult contains the result of the OAuth callback
+// OAuthResult contains the result of the OAuth callback.
+// It holds either the authorization code and state for successful authentication
+// or an error message if the authentication failed.
 type OAuthResult struct {
-	Code  string
+	// Code is the authorization code received from the OAuth provider
+	Code string
+	// State is the state parameter used to prevent CSRF attacks
 	State string
+	// Error contains any error message if the OAuth flow failed
 	Error string
 }
 
-// NewOAuthServer creates a new OAuth callback server
+// NewOAuthServer creates a new OAuth callback server.
+// It initializes the server with the specified port and creates channels
+// for handling OAuth results and errors.
+//
+// Parameters:
+//   - port: The port number on which the server should listen
+//
+// Returns:
+//   - *OAuthServer: A new OAuthServer instance
 func NewOAuthServer(port int) *OAuthServer {
 	return &OAuthServer{
 		port:       port,
@@ -39,8 +63,13 @@ func NewOAuthServer(port int) *OAuthServer {
 	}
 }
 
-// Start starts the OAuth callback server
-func (s *OAuthServer) Start(ctx context.Context) error {
+// Start starts the OAuth callback server.
+// It sets up the HTTP handlers for the callback and success endpoints,
+// and begins listening on the specified port.
+//
+// Returns:
+//   - error: An error if the server fails to start
+func (s *OAuthServer) Start() error {
 	s.mu.Lock()
 	defer s.mu.Unlock()
 
@@ -79,7 +108,14 @@ func (s *OAuthServer) Start(ctx context.Context) error {
 	return nil
 }
 
-// Stop gracefully stops the OAuth callback server
+// Stop gracefully stops the OAuth callback server.
+// It performs a graceful shutdown of the HTTP server with a timeout.
+//
+// Parameters:
+//   - ctx: The context for controlling the shutdown process
+//
+// Returns:
+//   - error: An error if the server fails to stop gracefully
 func (s *OAuthServer) Stop(ctx context.Context) error {
 	s.mu.Lock()
 	defer s.mu.Unlock()
@@ -101,7 +137,16 @@ func (s *OAuthServer) Stop(ctx context.Context) error {
 	return err
 }
 
-// WaitForCallback waits for the OAuth callback with a timeout
+// WaitForCallback waits for the OAuth callback with a timeout.
+// It blocks until either an OAuth result is received, an error occurs,
+// or the specified timeout is reached.
+//
+// Parameters:
+//   - timeout: The maximum time to wait for the callback
+//
+// Returns:
+//   - *OAuthResult: The OAuth result if successful
+//   - error: An error if the callback times out or an error occurs
 func (s *OAuthServer) WaitForCallback(timeout time.Duration) (*OAuthResult, error) {
 	select {
 	case result := <-s.resultChan:
@@ -113,7 +158,13 @@ func (s *OAuthServer) WaitForCallback(timeout time.Duration) (*OAuthResult, erro
 	}
 }
 
-// handleCallback handles the OAuth callback endpoint
+// handleCallback handles the OAuth callback endpoint.
+// It extracts the authorization code and state from the callback URL,
+// validates the parameters, and sends the result to the waiting channel.
+//
+// Parameters:
+//   - w: The HTTP response writer
+//   - r: The HTTP request
 func (s *OAuthServer) handleCallback(w http.ResponseWriter, r *http.Request) {
 	log.Debug("Received OAuth callback")
 
@@ -171,7 +222,12 @@ func (s *OAuthServer) handleCallback(w http.ResponseWriter, r *http.Request) {
 	http.Redirect(w, r, "/success", http.StatusFound)
 }
 
-// handleSuccess handles the success page endpoint
+// handleSuccess handles the success page endpoint.
+// It serves a user-friendly HTML page indicating that authentication was successful.
+//
+// Parameters:
+//   - w: The HTTP response writer
+//   - r: The HTTP request
 func (s *OAuthServer) handleSuccess(w http.ResponseWriter, r *http.Request) {
 	log.Debug("Serving success page")
 
@@ -195,7 +251,16 @@ func (s *OAuthServer) handleSuccess(w http.ResponseWriter, r *http.Request) {
 	}
 }
 
-// generateSuccessHTML creates the HTML content for the success page
+// generateSuccessHTML creates the HTML content for the success page.
+// It customizes the page based on whether additional setup is required
+// and includes a link to the platform.
+//
+// Parameters:
+//   - setupRequired: Whether additional setup is required after authentication
+//   - platformURL: The URL to the platform for additional setup
+//
+// Returns:
+//   - string: The HTML content for the success page
 func (s *OAuthServer) generateSuccessHTML(setupRequired bool, platformURL string) string {
 	html := LoginSuccessHtml
 
@@ -213,7 +278,11 @@ func (s *OAuthServer) generateSuccessHTML(setupRequired bool, platformURL string
 	return html
 }
 
-// sendResult sends the OAuth result to the waiting channel
+// sendResult sends the OAuth result to the waiting channel.
+// It ensures that the result is sent without blocking the handler.
+//
+// Parameters:
+//   - result: The OAuth result to send
 func (s *OAuthServer) sendResult(result *OAuthResult) {
 	select {
 	case s.resultChan <- result:
@@ -223,7 +292,11 @@ func (s *OAuthServer) sendResult(result *OAuthResult) {
 	}
 }
 
-// isPortAvailable checks if the specified port is available
+// isPortAvailable checks if the specified port is available.
+// It attempts to listen on the port to determine availability.
+//
+// Returns:
+//   - bool: True if the port is available, false otherwise
 func (s *OAuthServer) isPortAvailable() bool {
 	addr := fmt.Sprintf(":%d", s.port)
 	listener, err := net.Listen("tcp", addr)
@@ -236,7 +309,10 @@ func (s *OAuthServer) isPortAvailable() bool {
 	return true
 }
 
-// IsRunning returns whether the server is currently running
+// IsRunning returns whether the server is currently running.
+//
+// Returns:
+//   - bool: True if the server is running, false otherwise
 func (s *OAuthServer) IsRunning() bool {
 	s.mu.Lock()
 	defer s.mu.Unlock()