Documentation
¶
Index ¶
- func AdmissionMiddleware(checker coreruntime.AdmissionChecker, auditLogger *coreruntime.AuditLogger) func(http.Handler) http.Handler
- func DefaultAllowedOrigins() []string
- func DrainResponseHeaderStage(ctx context.Context, dst http.Header)
- func ResponseHeaderStageFromContext(ctx context.Context) http.Header
- func WithResponseHeaderStage(ctx context.Context) context.Context
- func WriteSSEEvent(w http.ResponseWriter, flusher http.Flusher, event string, data any) error
- type Handler
- type RateLimitConfig
- type SSEHandler
- type Server
- func (s *Server) Port() int
- func (s *Server) RegisterHTTPHandler(pattern string, handler http.HandlerFunc)
- func (s *Server) RegisterHandler(method string, h Handler)
- func (s *Server) RegisterSSEHandler(method string, h SSEHandler)
- func (s *Server) Shutdown(ctx context.Context) error
- func (s *Server) Start(ctx context.Context) error
- func (s *Server) TaskStore() *a2a.TaskStore
- func (s *Server) UpdateAgentCard(card *a2a.AgentCard)
- type ServerConfig
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AdmissionMiddleware ¶
func AdmissionMiddleware( checker coreruntime.AdmissionChecker, auditLogger *coreruntime.AuditLogger, ) func(http.Handler) http.Handler
AdmissionMiddleware gates inbound A2A requests on the platform's per-agent quota decision (issue #201). Wraps `next` with a check that runs AFTER the auth middleware on every request — denied requests short-circuit with HTTP 402 Payment Required + a structured body + the `task_admission_denied` audit event.
Forge fails open on platform errors (see PlatformAdmissionChecker fallback path). On admit the middleware is a pass-through; on deny it never reaches `next`.
Audit logging is optional — passing nil disables emission. The span is opened inside the checker (not here) so the underlying http.client call to the platform nests cleanly under admission.check; both wrapped and unwrapped paths benefit.
func DefaultAllowedOrigins ¶
func DefaultAllowedOrigins() []string
DefaultAllowedOrigins returns the default CORS origins for local development.
func DrainResponseHeaderStage ¶
DrainResponseHeaderStage copies every staged header from ctx onto the destination header (typically the response writer's). Uses Add (not Set) so handlers that legitimately want multi-value headers can produce them, though FWS-3's surface uses single-valued headers only.
nil stage → no-op. Empty stage → no-op. Called by the dispatcher between Handler return and writeJSON so the headers land on the envelope.
func ResponseHeaderStageFromContext ¶
ResponseHeaderStageFromContext returns the staging header attached by WithResponseHeaderStage, or nil when no stage was installed. Handlers that want to publish per-invocation response headers (typed FWS-3 usage telemetry, future cancellation reasons, etc.) read this and write to it. The dispatcher drains it via DrainResponseHeaderStage after the handler returns.
func WithResponseHeaderStage ¶
WithResponseHeaderStage attaches a fresh, empty http.Header to ctx. Call this from the JSON-RPC dispatcher exactly once per request, before invoking the registered Handler. The returned context must be the one passed to the Handler; otherwise the handler's ResponseHeaderStageFromContext lookup will miss.
func WriteSSEEvent ¶
WriteSSEEvent writes a single SSE event to the response writer.
Types ¶
type Handler ¶
type Handler func(ctx context.Context, id any, rawParams json.RawMessage) *a2a.JSONRPCResponse
Handler processes a JSON-RPC request and returns a response.
type RateLimitConfig ¶
type RateLimitConfig struct {
ReadRPS float64 // requests per second for read operations (GET/HEAD/OPTIONS)
ReadBurst int // burst size for reads
WriteRPS float64 // requests per second for write operations (POST/PUT/DELETE)
WriteBurst int // burst size for writes
// CancelExempt skips the write limiter for `tasks/cancel` JSON-RPC
// requests entirely. Default true. The cost-ceiling cancel-burst
// case (orchestrator firing N parallel cancels when a workflow
// budget trips) is the canonical example of why this exists —
// sharing the write bucket with tasks/send means the cancels are
// throttled at exactly the moment cancellation matters most.
// DoS via cancel-spam is naturally bounded by the registry's
// O(1) unknown-task lookup. See issue #110 / FWS-10.
CancelExempt bool
}
RateLimitConfig controls per-IP rate limiting on the A2A server.
Defaults (see defaultRateLimitConfig): 60/min for both reads and writes, with burst 10 / 20 respectively, and tasks/cancel exempt from the write bucket entirely. The bumped write defaults (vs the original #31 design of 10/min) reflect operational reality — orchestrated parallel-task dispatch and cron-fire bursts blow past the old 10/min in seconds. The cancel exemption is the most important change: cancel is "stop doing work," it's the recovery mechanism for runaway invocations, and throttling it amplifies the problem it's trying to solve. See issue #110 / FWS-10.
type SSEHandler ¶
type SSEHandler func(ctx context.Context, id any, rawParams json.RawMessage, w http.ResponseWriter, flusher http.Flusher)
SSEHandler streams SSE events for a JSON-RPC request.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server is an A2A-compliant HTTP server with JSON-RPC 2.0 dispatch.
func (*Server) Port ¶
Port returns the port the server is configured to listen on (or the actual port after Start resolves port conflicts).
func (*Server) RegisterHTTPHandler ¶
func (s *Server) RegisterHTTPHandler(pattern string, handler http.HandlerFunc)
RegisterHTTPHandler registers a standard HTTP handler on the server's mux. Used for REST-style endpoints alongside JSON-RPC.
func (*Server) RegisterHandler ¶
RegisterHandler registers a JSON-RPC method handler.
func (*Server) RegisterSSEHandler ¶
func (s *Server) RegisterSSEHandler(method string, h SSEHandler)
RegisterSSEHandler registers an SSE-streaming JSON-RPC method handler.
func (*Server) Start ¶
Start begins serving HTTP. It blocks until the context is cancelled or an error occurs.
func (*Server) UpdateAgentCard ¶
UpdateAgentCard replaces the agent card (for hot-reload).
type ServerConfig ¶
type ServerConfig struct {
Port int
Host string // bind address (default "" = all interfaces)
ShutdownTimeout time.Duration // graceful shutdown timeout (0 = immediate)
AgentCard *a2a.AgentCard
AuthMiddleware func(http.Handler) http.Handler // optional auth middleware
AllowedOrigins []string // CORS allowed origins
RateLimit *RateLimitConfig // optional rate limit config
}
ServerConfig configures the A2A HTTP server.
Source Files