nginx

package
v1.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 25, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package nginx provides Nginx configuration generation and management for the nSelf CLI. This file implements a thin wrapper for blue/green upstream weight management (T06).

Traffic splitting is achieved via Nginx weighted upstream blocks written to nginx/conf.d/bluegreen-upstream.conf and reloaded atomically with nginx -s reload. This keeps the nSelf-First doctrine: no direct Docker API calls, no hand-edited generated files — all routing goes through the nself CLI surface.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func GenerateWeightedUpstream added in v1.0.16

func GenerateWeightedUpstream(cfg UpstreamConfig, canaryPercent int) (string, error)

GenerateWeightedUpstream generates an nginx upstream block for blue/green traffic splitting. canaryPercent (0-100) controls how much traffic routes to green:

  • 0: all traffic to blue (initial state / after rollback)
  • 1-99: weighted split (canary)
  • 100: all traffic to green (post-promote)

Inactive servers are included as "backup" to avoid nginx config errors.

func HasDomainConflict

func HasDomainConflict(routes []NginxRoute) (bool, []string)

HasDomainConflict detects when two or more routes share the same server_name + location combination. Returns true and a list of conflict description strings if conflicts are found.

When NginxRoute.PluginName is set on both the current and previously-seen route, the conflict message uses the format:

route conflict: /api claimed by <pluginA> and <pluginB>

Types

type Generator

type Generator struct {
	// contains filtered or unexported fields
}

Generator builds nginx configuration files from project configuration.

func NewGenerator

func NewGenerator(cfg *config.Config, workdir string) *Generator

NewGenerator creates an nginx Generator from the given config. When SSL_MODE is "local" (or empty, which defaults to "local" in dev), nginx server blocks are generated with ssl_certificate directives pointing to the locally generated cert files. For other modes (letsencrypt, custom, none), the HTTPS server blocks are omitted so nginx can start without requiring cert files that do not yet exist.

func (*Generator) Generate

func (g *Generator) Generate() (map[string]string, error)

Generate produces all nginx config files. Returns map of filepath to content (relative to project root).

func (*Generator) RenderServiceRoute

func (g *Generator) RenderServiceRoute(data ServiceRouteData) (string, error)

RenderServiceRoute renders a single service route config from the service.conf.tmpl. Exported so external callers can render individual service routes. HasSSL in the provided data is always overridden by the generator's own hasSSL value, which is derived from SSL_MODE. Callers do not need to set it.

type NginxRoute

type NginxRoute struct {
	ServerName string // e.g. "auth.example.com"
	Location   string // e.g. "/" (always "/" in current templates)
	PluginName string // owning plugin name — used in conflict error messages
}

NginxRoute represents a single nginx server block route for conflict detection.

type ServiceRouteData

type ServiceRouteData struct {
	Route      string
	BaseDomain string
	Upstream   string
	// UpstreamName is the sanitized name of the generated `upstream {}` block.
	// Set automatically by the generator; callers do not populate it.
	UpstreamName string
	SSLDir       string
	RateZone     string
	Burst        int
	ConnLimit    int
	WebSocket    bool
	LazyResolve  bool
	// HasSSL controls whether ssl_certificate directives and the listen 443
	// directives are emitted. Set to false for letsencrypt/custom/none modes.
	HasSSL bool
	// HasTrustedChain controls whether ssl_trusted_certificate and OCSP
	// stapling are emitted.
	//
	// The template used to emit them unconditionally, pointing at a chain.pem
	// that `nself build` never writes — it emits only fullchain.pem and
	// privkey.pem. nginx then refused to start on every fresh project with
	// "cannot load certificate .../chain.pem: BIO_new_file() failed". Reported
	// by the ntask clean-fork self-host drill, 2026-08-24.
	//
	// Set by the generator from what is actually on disk; callers do not
	// populate it. Stapling is meaningless for a locally generated certificate
	// anyway — there is no OCSP responder for a cert nobody issued.
	HasTrustedChain bool
}

ServiceRouteData holds template data for service.conf.tmpl.

type UpstreamConfig added in v1.0.16

type UpstreamConfig struct {
	// UpstreamName is the nginx upstream block name. Default: "nself_api".
	UpstreamName string

	// BlueHost is the blue server address. Default: "127.0.0.1".
	BlueHost string

	// BluePort is the blue server port. Default: 8080.
	BluePort int

	// GreenHost is the green server address. Default: "127.0.0.1".
	GreenHost string

	// GreenPort is the green server port. Default: 8180.
	GreenPort int
}

UpstreamConfig holds the parameters for generating a blue/green upstream block.

func DefaultUpstreamConfig added in v1.0.16

func DefaultUpstreamConfig() UpstreamConfig

DefaultUpstreamConfig returns an UpstreamConfig with production defaults. Blue at 127.0.0.1:8080, green at 127.0.0.1:8180 (port offset +100).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL