feat: server middleware API

a2a/core.go

@@ -34,6 +34,8 @@ func (*Message) isSendMessageResult() {}
 // Event interface is used to represent types that can be sent over a streaming connection.
 type Event interface {
 	isEvent()
+
+	Meta() map[string]any
 }
 
 func (*Message) isEvent()                 {}
@@ -55,6 +57,8 @@ func NewMessageID() string {
 	return uuid.NewString()
 }
 
+var _ Event = (*Message)(nil)
+
 // Message represents a single message in the conversation between a user and an agent.
 type Message struct {
 	// ID is a unique identifier for the message, typically a UUID, generated by the sender.
@@ -106,6 +110,10 @@ func NewMessageForTask(role MessageRole, task *Task, parts ...Part) *Message {
 	}
 }
 
+func (m *Message) Meta() map[string]any {
+	return m.Metadata
+}
+
 // TaskID is a unique identifier for the task, generated by the server for a new task.
 type TaskID string
 
@@ -144,6 +152,8 @@ func (ts TaskState) Terminal() bool {
 		ts == TaskStateRejected
 }
 
+var _ Event = (*Task)(nil)
+
 // Task represents a single, stateful operation or conversation between a client and an agent.
 type Task struct {
 	// ID is a unique identifier for the task, generated by the server for a new task.
@@ -178,6 +188,10 @@ type TaskStatus struct {
 	Timestamp *time.Time `json:"timestamp,omitempty" yaml:"timestamp,omitempty" mapstructure:"timestamp,omitempty"`
 }
 
+func (m *Task) Meta() map[string]any {
+	return m.Metadata
+}
+
 // ArtifactID is a unique identifier for the artifact within the scope of the task.
 type ArtifactID string
 
@@ -207,6 +221,8 @@ type Artifact struct {
 	Parts ContentParts `json:"parts" yaml:"parts" mapstructure:"parts"`
 }
 
+var _ Event = (*TaskArtifactUpdateEvent)(nil)
+
 // TaskArtifactUpdateEvent is an event sent by the agent to notify the client that an artifact has been
 // generated or updated. This is typically used in streaming models.
 type TaskArtifactUpdateEvent struct {
@@ -230,6 +246,10 @@ type TaskArtifactUpdateEvent struct {
 	Metadata map[string]any `json:"metadata,omitempty" yaml:"metadata,omitempty" mapstructure:"metadata,omitempty"`
 }
 
+func (a *TaskArtifactUpdateEvent) Meta() map[string]any {
+	return a.Metadata
+}
+
 // NewArtifactEvent create a TaskArtifactUpdateEvent for an Artifact with a random ID.
 func NewArtifactEvent(task *Task, parts ...Part) *TaskArtifactUpdateEvent {
 	return &TaskArtifactUpdateEvent{
@@ -255,6 +275,8 @@ func NewArtifactUpdateEvent(task *Task, id ArtifactID, parts ...Part) *TaskArtif
 	}
 }
 
+var _ Event = (*TaskStatusUpdateEvent)(nil)
+
 // TaskStatusUpdateEvent is an event sent by the agent to notify the client of a change in a task's status.
 // This is typically used in streaming or subscription models.
 type TaskStatusUpdateEvent struct {
@@ -288,6 +310,10 @@ func NewStatusUpdateEvent(task *Task, state TaskState, msg *Message) *TaskStatus
 	}
 }
 
+func (a *TaskStatusUpdateEvent) Meta() map[string]any {
+	return a.Metadata
+}
+
 // ContentParts is an array of content parts that form the message body or an artifact.
 type ContentParts []Part
 

a2asrv/auth.go

@@ -0,0 +1,46 @@
+// Copyright 2025 The A2A Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package a2asrv
+
+// User can be attached to call context by authentication middleware.
+type User interface {
+	// Name returns a username.
+	Name() string
+	// Authenticated returns true if requested was authenticated.
+	Authenticated() bool
+}
+
+// AuthenticatedUser is a simple implementation of User interface which can be configured with a username.
+type AuthenticatedUser struct {
+	UserName string
+}
+
+func (u *AuthenticatedUser) Name() string {
+	return u.UserName
+}
+
+func (u *AuthenticatedUser) Authenticated() bool {
+	return true
+}
+
+type unauthenticatedUser struct{}
+
+func (unauthenticatedUser) Name() string {
+	return ""
+}
+
+func (unauthenticatedUser) Authenticated() bool {
+	return false
+}

a2asrv/extensions.go

@@ -0,0 +1,72 @@
+// Copyright 2025 The A2A Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package a2asrv
+
+import (
+	"context"
+	"slices"
+
+	"github.com/a2aproject/a2a-go/a2a"
+)
+
+const ExtensionsMetaKey = "X-A2A-Extensions"
+
+// Extensions provides utility methods for accessing extensions requested by the client and keeping track of extensions
+// activated during request processing.
+type Extensions struct {
+	callCtx *CallContext
+}
+
+// ExtensionsFrom is a helper function for quick access to Extensions in the current CallContext.
+func ExtensionsFrom(ctx context.Context) (*Extensions, bool) {
+	serverCallCtx, ok := CallContextFrom(ctx)
+	if !ok {
+		return nil, false
+	}
+	return serverCallCtx.Extensions(), true
+}
+
+// Active returns true if an extension has already been activated in the current CallContext using ExtensionContext.Activate.
+func (e *Extensions) Active(extension *a2a.AgentExtension) bool {
+	return slices.Contains(e.callCtx.activatedExtensions, extension.URI)
+}
+
+// Activate marks extension as activated in the current CallContext. A list of activated extensions might be attached as
+// response metadata by a transport implementation.
+func (e *Extensions) Activate(extension *a2a.AgentExtension) {
+	if e.Active(extension) {
+		return
+	}
+	e.callCtx.activatedExtensions = append(e.callCtx.activatedExtensions, extension.URI)
+}
+
+// ActivatedURIs returns all URIs activated during call execution.
+func (e *Extensions) ActivatedURIs() []string {
+	return slices.Clone(e.callCtx.activatedExtensions)
+}
+
+// Requested returns true if the provided extension was requested by the client.
+func (e *Extensions) Requested(extension *a2a.AgentExtension) bool {
+	return slices.Contains(e.RequestedURIs(), extension.URI)
+}
+
+// RequestedURIs returns all URIs of extensions requested by the client.
+func (e *Extensions) RequestedURIs() []string {
+	requested, ok := e.callCtx.RequestMeta().Get(ExtensionsMetaKey)
+	if !ok {
+		return []string{}
+	}
+	return slices.Clone(requested)
+}