lifecycle.go

// Copyright IBM Corp. 2022, 2026
// SPDX-License-Identifier: MPL-2.0

package consuldp

import (
	"context"
	"fmt"
	"net"
	"net/http"
	"strconv"
	"sync"
	"sync/atomic"
	"time"

	"github.com/hashicorp/go-hclog"

	"github.com/hashicorp/consul-dataplane/pkg/envoy"
)

const (
	// defaultLifecycleBindPort is the port which will serve the proxy lifecycle HTTP
	// endpoints on the loopback interface.
	defaultLifecycleBindPort = "20300"
	cdpLifecycleBindAddr     = "127.0.0.1"
	cdpLifecycleUrl          = "http://" + cdpLifecycleBindAddr

	defaultLifecycleShutdownPath = "/graceful_shutdown"
	defaultLifecycleStartupPath  = "/graceful_startup"
)

// lifecycleConfig handles all configuration related to managing the Envoy proxy
// lifecycle, including exposing management controls via an HTTP server.
type lifecycleConfig struct {
	logger hclog.Logger

	// consuldp proxy lifecycle management config
	shutdownDrainListenersEnabled bool
	shutdownGracePeriodSeconds    int
	gracefulAddr                  string
	gracefulPort                  int
	gracefulShutdownPath          string
	startupGracePeriodSeconds     int
	gracefulStartupPath           string
	dumpEnvoyConfigOnExitEnabled  bool

	// manager for controlling the Envoy proxy process
	proxy envoy.ProxyManager

	// consuldp proxy lifecycle management server
	lifecycleServer *http.Server

	// consuldp proxy lifecycle server control
	errorExitCh chan struct{}
	running     bool
	mu          sync.Mutex
}

func NewLifecycleConfig(cfg *Config, proxy envoy.ProxyManager) *lifecycleConfig {
	return &lifecycleConfig{
		shutdownDrainListenersEnabled: cfg.Envoy.ShutdownDrainListenersEnabled,
		shutdownGracePeriodSeconds:    cfg.Envoy.ShutdownGracePeriodSeconds,
		gracefulAddr:                  cfg.Envoy.GracefulAddr,
		gracefulPort:                  cfg.Envoy.GracefulPort,
		gracefulShutdownPath:          cfg.Envoy.GracefulShutdownPath,
		dumpEnvoyConfigOnExitEnabled:  cfg.Envoy.DumpEnvoyConfigOnExitEnabled,
		startupGracePeriodSeconds:     cfg.Envoy.StartupGracePeriodSeconds,
		gracefulStartupPath:           cfg.Envoy.GracefulStartupPath,
		proxy:                         proxy,

		errorExitCh: make(chan struct{}, 1),
		mu:          sync.Mutex{},
	}
}

func (m *lifecycleConfig) startLifecycleManager(ctx context.Context) error {
	m.mu.Lock()
	defer m.mu.Unlock()
	if m.running {
		return nil
	}

	m.logger = hclog.FromContext(ctx).Named("lifecycle")
	m.running = true
	go func() {
		<-ctx.Done()
		m.stopLifecycleServer()
	}()

	// Start the server which will expose HTTP endpoints for proxy lifecycle
	// management control
	mux := http.NewServeMux()

	m.logger.Info(fmt.Sprintf("setting graceful shutdown path: %s\n", m.shutdownPath()))
	mux.HandleFunc(m.shutdownPath(), m.gracefulShutdownHandler)

	m.logger.Info(fmt.Sprintf("setting graceful startup path: %s\n", m.startupPath()))
	mux.HandleFunc(m.startupPath(), m.gracefulStartupHandler)

	// Determine what the proxy lifecycle management server bind port is. It can be
	// set as a flag.
	cdpLifecycleBindAddr := cdpLifecycleBindAddr
	cdpLifecycleBindPort := defaultLifecycleBindPort
	if m.gracefulAddr != "" {
		cdpLifecycleBindAddr = m.gracefulAddr
	}
	if m.gracefulPort != 0 {
		cdpLifecycleBindPort = strconv.Itoa(m.gracefulPort)
	}
	m.lifecycleServer = &http.Server{
		Addr:    net.JoinHostPort(cdpLifecycleBindAddr, cdpLifecycleBindPort),
		Handler: mux,
	}

	// Start the proxy lifecycle management server
	go m.startLifecycleServer()

	return nil
}

// startLifecycleServer starts the main proxy lifecycle management server that
// exposes HTTP endpoints for proxy lifecycle control.
func (m *lifecycleConfig) startLifecycleServer() {
	m.logger.Info("starting proxy lifecycle management server", "address", m.lifecycleServer.Addr)
	err := m.lifecycleServer.ListenAndServe()
	if err != nil && err != http.ErrServerClosed {
		m.logger.Error("failed to serve proxy lifecycle management requests", "error", err)
		close(m.errorExitCh)
	}
}

// stopLifecycleServer stops the consul dataplane proxy lifecycle server
func (m *lifecycleConfig) stopLifecycleServer() {
	m.mu.Lock()
	defer m.mu.Unlock()
	m.running = false

	if m.lifecycleServer != nil {
		m.logger.Info("stopping the lifecycle management server")
		err := m.lifecycleServer.Close()
		if err != nil {
			m.logger.Warn("error while closing lifecycle server", "error", err)
			close(m.errorExitCh)
		}
	}
}

// lifecycleServerExited is used to signal that the lifecycle server
// recieved a signal to initiate shutdown.
func (m *lifecycleConfig) lifecycleServerExited() <-chan struct{} {
	return m.errorExitCh
}

func (m *lifecycleConfig) gracefulShutdownHandler(rw http.ResponseWriter, _ *http.Request) {
	// Kick off graceful shutdown in a separate goroutine to avoid blocking
	// sending an HTTP response
	go m.gracefulShutdown()

	// Return HTTP 200 Success
	rw.WriteHeader(http.StatusOK)
}

// gracefulShutdown blocks until shutdownGracePeriod seconds have elapsed, and, if
// configured, will drain inbound connections to Envoy listeners during that time.
func (m *lifecycleConfig) gracefulShutdown() {
	m.logger.Info("initiating shutdown")

	// Create a context that  will signal a cancel at the specified duration.
	// TODO: should this use lifecycleManager ctx instead of context.Background?
	timeout := time.Duration(m.shutdownGracePeriodSeconds) * time.Second
	ctx, cancel := context.WithTimeout(context.Background(), timeout)
	defer cancel()

	if m.dumpEnvoyConfigOnExitEnabled {
		m.logger.Info("dumping Envoy config to disk")
		err := m.proxy.DumpConfig()
		if err != nil {
			m.logger.Warn("error while attempting to dump Envoy config to disk", "error", err)
		}
	}

	m.logger.Info(fmt.Sprintf("waiting %d seconds before terminating dataplane proxy", m.shutdownGracePeriodSeconds))

	var wg sync.WaitGroup
	wg.Add(1)

	go func() {
		defer wg.Done()

		// If shutdownDrainListenersEnabled, initiatie graceful shutdown of Envoy.
		// We want to start draining connections from inbound listeners if
		// configured, but still allow outbound traffic until gracefulShutdownPeriod
		// has elapsed to facilitate a graceful application shutdown.
		if m.shutdownDrainListenersEnabled {
			err := m.proxy.Drain()
			if err != nil {
				m.logger.Warn("error while draining Envoy listeners", "error", err)
			}
		}

		// Block until context timeout has elapsed
		<-ctx.Done()

		// Finish graceful shutdown, quit Envoy proxy
		m.logger.Info("shutdown grace period timeout reached")
		err := m.proxy.Quit()
		if err != nil {
			m.logger.Warn("error while shutting down Envoy", "error", err)
		}
	}()

	// Wait for context timeout to elapse
	wg.Wait()
}

func (m *lifecycleConfig) gracefulStartupHandler(rw http.ResponseWriter, _ *http.Request) {
	//Unlike in gracefulShutdown, we want to delay the OK response until envoy is ready
	//in order to block application container.
	m.gracefulStartup()
	rw.WriteHeader(http.StatusOK)
}

// gracefulStartup blocks until the startup grace period has elapsed or we have confirmed that
// Envoy proxy is ready.
func (m *lifecycleConfig) gracefulStartup() {
	if m.startupGracePeriodSeconds == 0 {
		m.logger.Info("startupGracePeriodSeconds is set to 0, skipping graceful startup")
		return
	}

	ctx, cancel := context.WithTimeout(context.Background(), time.Duration(m.startupGracePeriodSeconds)*time.Second)
	defer cancel()

	var ready atomic.Bool
	go func() {
		for ctx.Err() == nil {
			r, err := m.proxy.Ready()
			if err != nil {
				m.logger.Info(fmt.Sprintf("error when querying proxy readiness: %s", err.Error()))
			} else {
				m.logger.Info(fmt.Sprintf("proxy readiness status: %v", r))
			}
			if r {
				ready.Store(true)
				cancel()
				break
			}
			time.Sleep(50 * time.Millisecond)
		}
	}()

	<-ctx.Done()
	if !ready.Load() {
		m.logger.Warn("grace period elapsed before proxy ready")
	} else {
		m.logger.Info("proxy is ready within the grace period")
	}
}

func (m *lifecycleConfig) shutdownPath() string {
	if m.gracefulShutdownPath == "" {
		// Set config to allow introspection of default path for testing
		m.gracefulShutdownPath = defaultLifecycleShutdownPath
	}

	return m.gracefulShutdownPath
}

func (m *lifecycleConfig) startupPath() string {
	if m.gracefulStartupPath == "" {
		// Set config to allow introspection of default path for testing
		m.gracefulStartupPath = defaultLifecycleStartupPath
	}

	return m.gracefulStartupPath
}