Function New

internal/httpapi/httpapi.go:274–344

New builds the v1 server. It installs the e2a error envelope globally, stands up the Huma API on a chi router under the `/v1` documentation paths, registers the ported operations, and points chi's not-found/ method-not-allowed handlers at the legacy surface.

(deps Deps)

// paths, registers the ported operations, and points chi's not-found/
// method-not-allowed handlers at the legacy surface.
func New(deps Deps) *Server {
	installErrorEnvelope()

	root := chi.NewRouter()
	root.Use(requestID)
	root.Use(securityHeaders)
	root.Use(authChallenge(deps.AuthChallenge))
	root.Use(withRawRequest)

	config := huma.DefaultConfig("e2a API", APIVersion)
	// Serve the spec and human docs under the versioned prefix so they sit
	// beside the operations (api-v1-redesign §1: everything lives under the
	// api host; here, under /v1).
	config.OpenAPIPath = "/v1/openapi"
	config.DocsPath = "/v1/docs"
	config.SchemasPath = "/v1/schemas"
	// Drop Huma's default schema-link transformer: it injects a `$schema`
	// field and Link header into response bodies, which would change the
	// clean contract shape this redesign is standardizing. Keep only our
	// request-id stamper.
	config.CreateHooks = nil
	config.Transformers = []huma.Transformer{stampRequestID}
	config.Info.Description = "e2a — authenticated email gateway for AI agents. v1 contract."
	// Canonical production host (api-v1-redesign §1: "Canonical base URL
	// https://api.e2a.dev/v1"). Operations already carry the /v1 prefix, so the
	// server URL stops at the host — otherwise clients would double it. Without a
	// servers block, generated SDKs default to http://localhost (a
	// Bearer-over-cleartext footgun).
	config.Servers = []*huma.Server{
		{URL: "https://api.e2a.dev", Description: "Production"},
	}
	// One auth scheme across the surface: a Bearer credential that is
	// either an API key or an OAuth 2.1 access token (api-v1-redesign §5).
	config.Components.SecuritySchemes = map[string]*huma.SecurityScheme{
		"bearer": {
			Type:        "http",
			Scheme:      "bearer",
			Description: "API key (e2a_…) or OAuth 2.1 access token, sent as `Authorization: Bearer <token>`.",
		},
	}

	api := humachi.New(root, config)

	s := &Server{Router: root, API: api, deps: deps}
	// Rate limiting runs as Huma middleware so it can stamp the IETF
	// RateLimit-* headers on the response and short-circuit a 429 before the
	// handler. Registered once; applies to every operation.
	api.UseMiddleware(s.rateLimit)
	s.registerOperations()

	// WebSocket transport — registered directly on chi (not Huma; it's a raw
	// upgrade, not a JSON operation). First-class /v1 inbound transport.
	if deps.WSHandle != nil {
		root.Get("/v1/agents/{email}/ws", func(w http.ResponseWriter, r *http.Request) {
			deps.WSHandle(w, r, chi.URLParam(r, "email"))
		})
	}