init
This commit is contained in:
@@ -0,0 +1,249 @@
|
||||
{
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"title": "A2A Protocol Schemas",
|
||||
"description": "Non-normative JSON Schema bundle extracted from proto definitions.",
|
||||
"version": "v1",
|
||||
"definitions": {
|
||||
"Struct": {
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"title": "Struct",
|
||||
"type": "object"
|
||||
},
|
||||
"Timestamp": {
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"format": "date-time",
|
||||
"title": "Timestamp",
|
||||
"type": "string"
|
||||
},
|
||||
"Value": {
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"title": "Value"
|
||||
},
|
||||
"API Key Security Scheme": {
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"additionalProperties": false,
|
||||
"description": "Defines a security scheme using an API key.",
|
||||
"properties": {
|
||||
"description": { "default": "", "description": "An optional description for the security scheme.", "type": "string" },
|
||||
"location": { "default": "", "description": "The location of the API key. Valid values are \"query\", \"header\", or \"cookie\".", "type": "string" },
|
||||
"name": { "default": "", "description": "The name of the header, query, or cookie parameter to be used.", "type": "string" }
|
||||
},
|
||||
"title": "API Key Security Scheme",
|
||||
"type": "object"
|
||||
},
|
||||
"Agent Capabilities": {
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"additionalProperties": false,
|
||||
"description": "Defines optional capabilities supported by an agent.",
|
||||
"properties": {
|
||||
"extendedAgentCard": { "description": "Indicates if the agent supports providing an extended agent card when authenticated.", "type": "boolean" },
|
||||
"extensions": { "description": "A list of protocol extensions supported by the agent.", "items": { "$ref": "lf.a2a.v1.AgentExtension.jsonschema.json" }, "type": "array" },
|
||||
"pushNotifications": { "description": "Indicates if the agent supports sending push notifications for asynchronous task updates.", "type": "boolean" },
|
||||
"streaming": { "description": "Indicates if the agent supports streaming responses.", "type": "boolean" }
|
||||
},
|
||||
"title": "Agent Capabilities",
|
||||
"type": "object"
|
||||
},
|
||||
"Agent Card": {
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"additionalProperties": false,
|
||||
"description": "A self-describing manifest for an agent. It provides essential metadata including the agent's identity, capabilities, skills, supported communication methods, and security requirements.",
|
||||
"properties": {
|
||||
"capabilities": { "$ref": "lf.a2a.v1.AgentCapabilities.jsonschema.json", "description": "A2A Capability set supported by the agent." },
|
||||
"defaultInputModes": { "description": "The set of interaction modes that the agent supports across all skills. Defined as media types.", "items": { "type": "string" }, "type": "array" },
|
||||
"defaultOutputModes": { "description": "The media types supported as outputs from this agent.", "items": { "type": "string" }, "type": "array" },
|
||||
"description": { "default": "", "description": "A human-readable description of the agent.", "type": "string" },
|
||||
"documentationUrl": { "description": "A URL providing additional documentation about the agent.", "type": "string" },
|
||||
"iconUrl": { "description": "Optional. A URL to an icon for the agent.", "type": "string" },
|
||||
"name": { "default": "", "description": "A human readable name for the agent.", "type": "string" },
|
||||
"provider": { "$ref": "lf.a2a.v1.AgentProvider.jsonschema.json", "description": "The service provider of the agent." },
|
||||
"securityRequirements": { "description": "Security requirements for contacting the agent.", "items": { "$ref": "lf.a2a.v1.SecurityRequirement.jsonschema.json" }, "type": "array" },
|
||||
"securitySchemes": { "additionalProperties": { "$ref": "lf.a2a.v1.SecurityScheme.jsonschema.json" }, "description": "The security scheme details used for authenticating with this agent.", "type": "object" },
|
||||
"signatures": { "description": "JSON Web Signatures computed for this AgentCard.", "items": { "$ref": "lf.a2a.v1.AgentCardSignature.jsonschema.json" }, "type": "array" },
|
||||
"skills": { "description": "Skills represent the abilities of an agent.", "items": { "$ref": "lf.a2a.v1.AgentSkill.jsonschema.json" }, "type": "array" },
|
||||
"supportedInterfaces": { "description": "Ordered list of supported interfaces. The first entry is preferred.", "items": { "$ref": "lf.a2a.v1.AgentInterface.jsonschema.json" }, "type": "array" },
|
||||
"version": { "default": "", "description": "The version of the agent.", "type": "string" }
|
||||
},
|
||||
"title": "Agent Card",
|
||||
"type": "object"
|
||||
},
|
||||
"Agent Interface": {
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"additionalProperties": false,
|
||||
"description": "Declares a combination of a target URL, transport and protocol version for interacting with the agent.",
|
||||
"properties": {
|
||||
"protocolBinding": { "default": "", "description": "The protocol binding supported at this URL. Core ones: JSONRPC, GRPC, HTTP+JSON.", "type": "string" },
|
||||
"protocolVersion": { "default": "", "description": "The version of the A2A protocol this interface exposes. Examples: \"0.3\", \"1.0\"", "type": "string" },
|
||||
"tenant": { "default": "", "description": "Tenant ID to be used in the request when calling the agent.", "type": "string" },
|
||||
"url": { "default": "", "description": "The URL where this interface is available.", "type": "string" }
|
||||
},
|
||||
"title": "Agent Interface",
|
||||
"type": "object"
|
||||
},
|
||||
"Agent Provider": {
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"additionalProperties": false,
|
||||
"description": "Represents the service provider of an agent.",
|
||||
"properties": {
|
||||
"organization": { "default": "", "description": "The name of the agent provider's organization.", "type": "string" },
|
||||
"url": { "default": "", "description": "A URL for the agent provider's website or relevant documentation.", "type": "string" }
|
||||
},
|
||||
"title": "Agent Provider",
|
||||
"type": "object"
|
||||
},
|
||||
"Agent Skill": {
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"additionalProperties": false,
|
||||
"description": "Represents a distinct capability or function that an agent can perform.",
|
||||
"properties": {
|
||||
"description": { "default": "", "description": "A detailed description of the skill.", "type": "string" },
|
||||
"examples": { "description": "Example prompts or scenarios that this skill can handle.", "items": { "type": "string" }, "type": "array" },
|
||||
"id": { "default": "", "description": "A unique identifier for the agent's skill.", "type": "string" },
|
||||
"inputModes": { "description": "The set of supported input media types for this skill.", "items": { "type": "string" }, "type": "array" },
|
||||
"name": { "default": "", "description": "A human-readable name for the skill.", "type": "string" },
|
||||
"outputModes": { "description": "The set of supported output media types for this skill.", "items": { "type": "string" }, "type": "array" },
|
||||
"tags": { "description": "A set of keywords describing the skill's capabilities.", "items": { "type": "string" }, "type": "array" }
|
||||
},
|
||||
"title": "Agent Skill",
|
||||
"type": "object"
|
||||
},
|
||||
"Artifact": {
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"additionalProperties": false,
|
||||
"description": "Artifacts represent task outputs.",
|
||||
"properties": {
|
||||
"artifactId": { "default": "", "description": "Unique identifier (e.g. UUID) for the artifact. It must be unique within a task.", "type": "string" },
|
||||
"description": { "default": "", "description": "Optional. A human readable description of the artifact.", "type": "string" },
|
||||
"extensions": { "description": "The URIs of extensions that are present or contributed to this Artifact.", "items": { "type": "string" }, "type": "array" },
|
||||
"name": { "default": "", "description": "A human readable name for the artifact.", "type": "string" },
|
||||
"parts": { "description": "The content of the artifact. Must contain at least one part.", "items": { "$ref": "lf.a2a.v1.Part.jsonschema.json" }, "type": "array" }
|
||||
},
|
||||
"title": "Artifact",
|
||||
"type": "object"
|
||||
},
|
||||
"Message": {
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"additionalProperties": false,
|
||||
"description": "Message is one unit of communication between client and server. It can be associated with a context and/or a task.",
|
||||
"properties": {
|
||||
"contextId": { "default": "", "description": "Optional. The context id of the message.", "type": "string" },
|
||||
"extensions": { "description": "The URIs of extensions that are present or contributed to this Message.", "items": { "type": "string" }, "type": "array" },
|
||||
"messageId": { "default": "", "description": "The unique identifier (e.g. UUID) of the message.", "type": "string" },
|
||||
"parts": { "description": "Parts is the container of the message content.", "items": { "$ref": "lf.a2a.v1.Part.jsonschema.json" }, "type": "array" },
|
||||
"referenceTaskIds": { "description": "A list of task IDs that this message references for additional context.", "items": { "type": "string" }, "type": "array" },
|
||||
"role": {
|
||||
"anyOf": [
|
||||
{ "pattern": "^ROLE_UNSPECIFIED$", "type": "string" },
|
||||
{ "enum": ["ROLE_USER", "ROLE_AGENT"], "type": "string" },
|
||||
{ "maximum": 2147483647, "minimum": -2147483648, "type": "integer" }
|
||||
],
|
||||
"default": 0,
|
||||
"description": "Identifies the sender of the message.",
|
||||
"title": "Role"
|
||||
},
|
||||
"taskId": { "default": "", "description": "Optional. The task id of the message.", "type": "string" }
|
||||
},
|
||||
"title": "Message",
|
||||
"type": "object"
|
||||
},
|
||||
"Part": {
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"additionalProperties": false,
|
||||
"description": "Part represents a container for a section of communication content. Parts can be purely textual, some sort of file (image, video, etc) or a structured data blob (i.e. JSON).",
|
||||
"properties": {
|
||||
"filename": { "default": "", "description": "An optional filename for the file (e.g., \"document.pdf\").", "type": "string" },
|
||||
"mediaType": { "default": "", "description": "The media_type (MIME type) of the part content (e.g., \"text/plain\", \"application/json\", \"image/png\").", "type": "string" },
|
||||
"raw": { "description": "The raw byte content of a file. In JSON serialization, this is encoded as a base64 string.", "pattern": "^[A-Za-z0-9+/]*={0,2}$", "type": "string" },
|
||||
"text": { "description": "The string content of the text part.", "type": "string" },
|
||||
"url": { "description": "A url pointing to the file's content.", "type": "string" }
|
||||
},
|
||||
"title": "Part",
|
||||
"type": "object"
|
||||
},
|
||||
"Task": {
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"additionalProperties": false,
|
||||
"description": "Task is the core unit of action for A2A. It has a current status and when results are created for the task they are stored in the artifact.",
|
||||
"properties": {
|
||||
"artifacts": { "description": "A set of output artifacts for a Task.", "items": { "$ref": "lf.a2a.v1.Artifact.jsonschema.json" }, "type": "array" },
|
||||
"contextId": { "default": "", "description": "Unique identifier (e.g. UUID) for the contextual collection of interactions.", "type": "string" },
|
||||
"history": { "description": "The history of interactions from a Task.", "items": { "$ref": "lf.a2a.v1.Message.jsonschema.json" }, "type": "array" },
|
||||
"id": { "default": "", "description": "Unique identifier (e.g. UUID) for the task, generated by the server for a new task.", "type": "string" },
|
||||
"status": { "$ref": "lf.a2a.v1.TaskStatus.jsonschema.json", "description": "The current status of a Task, including state and a message." }
|
||||
},
|
||||
"title": "Task",
|
||||
"type": "object"
|
||||
},
|
||||
"Task Status": {
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"additionalProperties": false,
|
||||
"description": "A container for the status of a task",
|
||||
"properties": {
|
||||
"message": { "$ref": "lf.a2a.v1.Message.jsonschema.json", "description": "A message associated with the status." },
|
||||
"state": {
|
||||
"anyOf": [
|
||||
{ "pattern": "^TASK_STATE_UNSPECIFIED$", "type": "string" },
|
||||
{ "enum": ["TASK_STATE_SUBMITTED", "TASK_STATE_WORKING", "TASK_STATE_COMPLETED", "TASK_STATE_FAILED", "TASK_STATE_CANCELED", "TASK_STATE_INPUT_REQUIRED", "TASK_STATE_REJECTED", "TASK_STATE_AUTH_REQUIRED"], "type": "string" },
|
||||
{ "maximum": 2147483647, "minimum": -2147483648, "type": "integer" }
|
||||
],
|
||||
"default": 0,
|
||||
"description": "The current state of this task.",
|
||||
"title": "Task State"
|
||||
},
|
||||
"timestamp": { "description": "ISO 8601 Timestamp when the status was recorded.", "format": "date-time", "type": "string" }
|
||||
},
|
||||
"title": "Task Status",
|
||||
"type": "object"
|
||||
},
|
||||
"Send Message Request": {
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"additionalProperties": false,
|
||||
"description": "Represents a request for the SendMessage method.",
|
||||
"properties": {
|
||||
"configuration": { "$ref": "lf.a2a.v1.SendMessageConfiguration.jsonschema.json", "description": "Configuration for the send request." },
|
||||
"message": { "$ref": "lf.a2a.v1.Message.jsonschema.json", "description": "The message to send to the agent." },
|
||||
"tenant": { "default": "", "description": "Optional. Tenant ID, provided as a path parameter.", "type": "string" }
|
||||
},
|
||||
"title": "Send Message Request",
|
||||
"type": "object"
|
||||
},
|
||||
"Send Message Response": {
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"additionalProperties": false,
|
||||
"description": "Represents the response for the SendMessage method.",
|
||||
"properties": {
|
||||
"message": { "$ref": "lf.a2a.v1.Message.jsonschema.json", "description": "A message from the agent." },
|
||||
"task": { "$ref": "lf.a2a.v1.Task.jsonschema.json", "description": "The task created or updated by the message." }
|
||||
},
|
||||
"title": "Send Message Response",
|
||||
"type": "object"
|
||||
},
|
||||
"Security Requirement": {
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"additionalProperties": false,
|
||||
"description": "Defines the security requirements for an agent.",
|
||||
"properties": {
|
||||
"schemes": { "additionalProperties": { "$ref": "lf.a2a.v1.StringList.jsonschema.json" }, "description": "A map of security schemes to the required scopes.", "type": "object" }
|
||||
},
|
||||
"title": "Security Requirement",
|
||||
"type": "object"
|
||||
},
|
||||
"Security Scheme": {
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"additionalProperties": false,
|
||||
"description": "Defines a security scheme that can be used to secure an agent's endpoints. Based on OpenAPI 3.2 Security Scheme Object.",
|
||||
"properties": {
|
||||
"apiKeySecurityScheme": { "$ref": "lf.a2a.v1.APIKeySecurityScheme.jsonschema.json", "description": "API key-based authentication." },
|
||||
"httpAuthSecurityScheme": { "$ref": "lf.a2a.v1.HTTPAuthSecurityScheme.jsonschema.json", "description": "HTTP authentication (Basic, Bearer, etc.)." },
|
||||
"mtlsSecurityScheme": { "$ref": "lf.a2a.v1.MutualTlsSecurityScheme.jsonschema.json", "description": "Mutual TLS authentication." },
|
||||
"oauth2SecurityScheme": { "$ref": "lf.a2a.v1.OAuth2SecurityScheme.jsonschema.json", "description": "OAuth 2.0 authentication." },
|
||||
"openIdConnectSecurityScheme": { "$ref": "lf.a2a.v1.OpenIdConnectSecurityScheme.jsonschema.json", "description": "OpenID Connect authentication." }
|
||||
},
|
||||
"title": "Security Scheme",
|
||||
"type": "object"
|
||||
}
|
||||
},
|
||||
"_source": "https://a2a-protocol.org/latest/spec/a2a.json",
|
||||
"_retrieved": "2026-06-07",
|
||||
"_note": "Condensed from official A2A Protocol JSON Schema bundle v1"
|
||||
}
|
||||
@@ -0,0 +1,75 @@
|
||||
# Agent2Agent (A2A) Samples
|
||||
|
||||
Welcome to the official code samples and demonstrations for the [Agent2Agent (A2A) Protocol](https://goo.gle/a2a).
|
||||
|
||||
Whether you are exploring multi-agent architectures for the first time or building advanced interoperable agent networks, this repository provides simple, inspiring, and accessible learning resources to accelerate your development.
|
||||
|
||||
## Why Agent2Agent?
|
||||
|
||||
In a world of diverse AI frameworks and ecosystems, agents need a common language to communicate, collaborate, and delegate tasks securely. The A2A protocol establishes a standardized, open standard for multi-agent interoperability.
|
||||
|
||||
Our samples demonstrate how easily complex multi-agent problems can be solved across different languages and host applications.
|
||||
|
||||
## Quick Start
|
||||
|
||||
Get up and running immediately by launching a Helloworld agent and communicating with it via our Python CLI host.
|
||||
|
||||
1. **Start the Agent Server**:
|
||||
Open a terminal and start the Helloworld agent server:
|
||||
|
||||
```bash
|
||||
cd samples/python/agents/helloworld
|
||||
uv run .
|
||||
```
|
||||
|
||||
2. **Run the Host Client**:
|
||||
Open a second terminal and run the CLI client to send a task to the agent:
|
||||
|
||||
```bash
|
||||
cd samples/python/agents/helloworld
|
||||
uv run test_client.py
|
||||
```
|
||||
|
||||
## Repository Structure
|
||||
|
||||
The repository is organized into several key directories by language:
|
||||
|
||||
| Directory | Description |
|
||||
| --- | --- |
|
||||
| [samples](/samples) | Core A2A samples organized by programming language. |
|
||||
| [samples/python](/samples/python) | Demonstrates Python agent implementations using the A2A Python SDK. |
|
||||
| [samples/go](/samples/go) | Demonstrates Go agent implementations using the A2A Go SDK. |
|
||||
| [samples/dotnet](/samples/dotnet) | Demonstrates C# agent implementations using the A2A .NET SDK. |
|
||||
| [samples/java](/samples/java) | Demonstrates Java agent implementations using the A2A Java SDK. |
|
||||
| [samples/js](/samples/js) | Demonstrates Node.js agent implementations using the A2A JavaScript SDK. |
|
||||
|
||||
## Contributing
|
||||
|
||||
We welcome and encourage contributions of all skill levels! If you have an idea for a new sample, a bug fix, or a documentation improvement, please check out our [Contributing Guide](CONTRIBUTING.md).
|
||||
|
||||
## Getting Help
|
||||
|
||||
If you have questions, feedback, or run into any issues, please reach out on our [issues page](https://github.com/a2aproject/a2a-samples/issues).
|
||||
|
||||
## Related Repositories
|
||||
|
||||
| Repository | Category | Description |
|
||||
| --- | --- | --- |
|
||||
| [A2A](https://github.com/a2aproject/A2A) | Core Specification | A2A Specification and documentation. |
|
||||
| [a2a-inspector](https://github.com/a2aproject/a2a-inspector) | Tooling | UI tool for inspecting A2A enabled agents. |
|
||||
| [a2a-tck](https://github.com/a2aproject/a2a-tck) | Testing | Test suite for validating A2A Protocol compliance. |
|
||||
| [a2a-python](https://github.com/a2aproject/a2a-python) | SDK (Python) | Official Python SDK for A2A. |
|
||||
| [a2a-go](https://github.com/a2aproject/a2a-go) | SDK (Go) | Official Go SDK for A2A. |
|
||||
| [a2a-java](https://github.com/a2aproject/a2a-java) | SDK (Java) | Official Java SDK for A2A. |
|
||||
| [a2a-js](https://github.com/a2aproject/a2a-js) | SDK (JavaScript) | Official Node.js/JavaScript SDK for A2A. |
|
||||
| [a2a-dotnet](https://github.com/a2aproject/a2a-dotnet) | SDK (C#/.NET) | Official C#/.NET SDK for A2A. |
|
||||
| [a2a-rs](https://github.com/a2aproject/a2a-rs) | SDK (Rust) | Official Rust SDK for A2A. |
|
||||
|
||||
## Security Disclaimer
|
||||
|
||||
**Important:** The sample code provided is for demonstration purposes and illustrates the mechanics of the Agent-to-Agent (A2A) protocol. When building production applications, it is critical to treat any agent operating outside of your direct control as a potentially untrusted entity.
|
||||
|
||||
All data received from an external agent—including but not limited to its AgentCard, messages, artifacts, and task statuses—should be handled as untrusted input. Developers are responsible for implementing appropriate security measures, such as input validation and secure handling of credentials to protect their systems and users.
|
||||
|
||||
---
|
||||
*Source: https://raw.githubusercontent.com/a2aproject/a2a-samples/main/README.md — Retrieved 2026-06-07*
|
||||
@@ -0,0 +1,125 @@
|
||||
# A2A and MCP: Detailed Comparison
|
||||
|
||||
In AI agent development, two key protocol types emerge to facilitate
|
||||
interoperability. One connects agents to tools and resources. The other enables
|
||||
agent-to-agent collaboration. The Agent2Agent (A2A) Protocol and the
|
||||
[Model Context Protocol](https://modelcontextprotocol.io/) (MCP) address these distinct but highly complementary needs.
|
||||
|
||||
## Model Context Protocol
|
||||
|
||||
The Model Context Protocol (MCP) defines how an AI agent interacts with and utilizes individual tools and resources, such as a database or an API.
|
||||
|
||||
This protocol offers the following capabilities:
|
||||
|
||||
- Standardizes how AI models and agents connect to and interact with tools,
|
||||
APIs, and other external resources.
|
||||
- Defines a structured way to describe tool capabilities, similar to function
|
||||
calling in Large Language Models.
|
||||
- Passes inputs to tools and receives structured outputs.
|
||||
- Supports common use cases, such as an LLM calling an external API, an agent
|
||||
querying a database, or an agent connecting to predefined functions.
|
||||
|
||||
## Agent2Agent Protocol
|
||||
|
||||
The Agent2Agent Protocol focuses on enabling different agents to collaborate with one another to achieve a common goal.
|
||||
|
||||
This protocol offers the following capabilities:
|
||||
|
||||
- Standardizes how independent, often opaque, AI agents communicate and
|
||||
collaborate as peers.
|
||||
- Provides an application-level protocol for agents to discover each other,
|
||||
negotiate interactions, manage shared tasks, and exchange conversational
|
||||
context and complex data.
|
||||
- Supports typical use cases, including a customer service agent delegating an
|
||||
inquiry to a billing agent, or a travel agent coordinating with flight,
|
||||
hotel, and activity agents.
|
||||
|
||||
## Why Different Protocols?
|
||||
|
||||
Both the MCP and A2A protocols are essential for building complex AI systems, and they address distinct but highly complementary needs. The distinction between A2A and MCP depends on what an agent interacts with.
|
||||
|
||||
- **Tools and Resources (MCP Domain)**:
|
||||
- **Characteristics:** These are typically primitives with well-defined,
|
||||
structured inputs and outputs. They perform specific, often stateless,
|
||||
functions. Examples include a calculator, a database query API, or a
|
||||
weather lookup service.
|
||||
- **Purpose:** Agents use tools to gather information and perform discrete
|
||||
functions.
|
||||
- **Agents (A2A domain)**:
|
||||
- **Characteristics:** These are more autonomous systems. They reason,
|
||||
plan, use multiple tools, maintain state over longer interactions, and
|
||||
engage in complex, often multi-turn dialogues to achieve novel or
|
||||
evolving tasks.
|
||||
- **Purpose:** Agents collaborate with other agents to tackle broader, more
|
||||
complex goals.
|
||||
|
||||
## A2A and MCP: Complementary Protocols for Agentic Systems
|
||||
|
||||
An agentic application might primarily use A2A to communicate with other agents.
|
||||
Each individual agent internally uses MCP to interact with its specific tools
|
||||
and resources.
|
||||
|
||||
### Example Scenario: The Auto Repair Shop
|
||||
|
||||
Consider an auto repair shop staffed by autonomous AI agent "mechanics".
|
||||
These mechanics use special-purpose tools, such as vehicle diagnostic scanners,
|
||||
repair manuals, and platform lifts, to diagnose and repair problems. The repair
|
||||
process can involve extensive conversations, research, and interaction with part
|
||||
suppliers.
|
||||
|
||||
- **Customer Interaction (User-to-Agent using A2A)**: A customer (or their
|
||||
primary assistant agent) uses A2A to communicate with the "Shop Manager"
|
||||
agent.
|
||||
|
||||
For example, the customer might say, "My car is making a rattling noise".
|
||||
|
||||
- **Multi-turn Diagnostic Conversation (Agent-to-Agent using A2A)**: The Shop
|
||||
Manager agent uses A2A for a multi-turn diagnostic conversation.
|
||||
|
||||
For example, the Manager might ask, "Can you send a video of the noise?" or "I see some fluid leaking. How long has this been happening?".
|
||||
|
||||
- **Internal Tool Usage (Agent-to-Tool using MCP)**: The Mechanic agent,
|
||||
assigned the task by the Shop Manager, needs to diagnose the issue. The
|
||||
Mechanic agent uses MCP to interact with its specialized tools.
|
||||
|
||||
For example:
|
||||
|
||||
- MCP call to a "Vehicle Diagnostic Scanner" tool:
|
||||
`scan_vehicle_for_error_codes(vehicle_id='XYZ123')`
|
||||
- MCP call to a "Repair Manual Database" tool:
|
||||
`get_repair_procedure(error_code='P0300', vehicle_make='Toyota',
|
||||
vehicle_model='Camry')`
|
||||
- MCP call to a "Platform Lift" tool: `raise_platform(height_meters=2)`
|
||||
|
||||
- **Supplier Interaction (Agent-to-Agent using A2A)**: The Mechanic agent
|
||||
determines that a specific part is needed. The Mechanic agent uses A2A to
|
||||
communicate with a "Parts Supplier" agent to order a part.
|
||||
|
||||
- **Order processing (Agent-to-Agent using A2A)**: The Parts Supplier agent,
|
||||
which is also an A2A-compliant system, responds, potentially leading to an
|
||||
order.
|
||||
|
||||
In this example:
|
||||
|
||||
- A2A facilitates the higher-level, conversational, and task-oriented
|
||||
interactions between the customer and the shop, and between the shop's
|
||||
agents and external supplier agents.
|
||||
- MCP enables the mechanic agent to use its specific, structured tools to
|
||||
perform its diagnostic and repair functions.
|
||||
|
||||
An A2A server could expose some of its skills as MCP-compatible resources.
|
||||
However, A2A's primary strength lies in its support for more flexible, stateful,
|
||||
and collaborative interactions. These interactions go beyond a typical tool
|
||||
invocation. A2A focuses on agents partnering on tasks, whereas MCP focuses on
|
||||
agents using capabilities.
|
||||
|
||||
## Representing A2A Agents as MCP Resources
|
||||
|
||||
An A2A Server (a remote agent) could expose some of its skills as MCP-compatible resources, especially if those skills are well-defined and can be invoked in a more tool-like, stateless manner. In such a case, another agent might "discover" this A2A agent's specific skill through an MCP-style tool description (perhaps derived from its Agent Card).
|
||||
|
||||
However, the primary strength of A2A lies in its support for more flexible, stateful, and collaborative interactions that go beyond typical tool invocation. A2A is about agents _partnering_ on tasks, while MCP is more about agents _using_ capabilities.
|
||||
|
||||
By leveraging both A2A for inter-agent collaboration and MCP for tool integration, developers can build more powerful, flexible, and interoperable AI systems.
|
||||
|
||||
---
|
||||
*Source: https://a2a-protocol.org/latest/topics/a2a-and-mcp/ and https://raw.githubusercontent.com/a2aproject/A2A/main/docs/topics/a2a-and-mcp.md — Retrieved 2026-06-07*
|
||||
@@ -0,0 +1,66 @@
|
||||
# ETSI EN 302 637-2 — ITS V2X Standard (Metadata)
|
||||
|
||||
## Bibliographic Metadata
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| Standard Number | ETSI EN 302 637-2 V1.4.1 |
|
||||
| Title | Intelligent Transport Systems (ITS); Vehicular Communications; Basic Set of Applications; Part 2: Specification of Cooperative Awareness Basic Service |
|
||||
| Publisher | ETSI (European Telecommunications Standards Institute) |
|
||||
| Year | 2019 |
|
||||
| Category | ITS-G5 / V2X (Vehicle-to-Everything) |
|
||||
| Direct PDF | https://www.etsi.org/deliver/etsi_en/302600_302699/30263702/01.04.01_60/en_30263702v010401p.pdf |
|
||||
| ETSI Portal | https://www.etsi.org/deliver/etsi_en/302600_302699/30263702/01.04.01_60/ |
|
||||
|
||||
## Standard Overview
|
||||
|
||||
ETSI EN 302 637-2 defines the **Cooperative Awareness Basic Service (CAM)** — the core
|
||||
broadcast service in ITS-G5 (European V2X standard based on IEEE 802.11p / ETSI ITS).
|
||||
|
||||
### Key Components
|
||||
- **CAM (Cooperative Awareness Message)**: Periodic broadcast (1–10 Hz) containing vehicle
|
||||
position, speed, heading, acceleration, and status (lights, brake status, etc.)
|
||||
- **CA Basic Service**: The service layer managing CAM generation, transmission, and reception
|
||||
- **Triggering conditions**: Time-based and event-triggered (change in heading > 4°, speed change > 0.5 m/s, position change > 4 m)
|
||||
- **Frequency**: 5.9 GHz ITS-G5 band (ETSI EN 302 663)
|
||||
|
||||
### Message Structure (CAM)
|
||||
```
|
||||
CAM ::= SEQUENCE {
|
||||
header ItsPduHeader,
|
||||
cam CoopAwareness
|
||||
}
|
||||
CoopAwareness ::= SEQUENCE {
|
||||
generationDeltaTime GenerationDeltaTime,
|
||||
camParameters CamParameters
|
||||
}
|
||||
CamParameters ::= SEQUENCE {
|
||||
basicContainer BasicContainer,
|
||||
highFrequencyContainer HighFrequencyContainer,
|
||||
lowFrequencyContainer LowFrequencyContainer OPTIONAL,
|
||||
specialVehicleContainer SpecialVehicleContainer OPTIONAL
|
||||
}
|
||||
```
|
||||
|
||||
### Relation to ITS-G5 Stack
|
||||
| Layer | Standard |
|
||||
|-------|---------|
|
||||
| Application | ETSI EN 302 637-2 (CAM), EN 302 637-3 (DENM) |
|
||||
| Facilities | ETSI EN 302 665 |
|
||||
| Networking & Transport | ETSI EN 302 636-4-1 (GeoNetworking) |
|
||||
| Access | ETSI EN 302 663 (ITS-G5 / IEEE 802.11p) |
|
||||
| Physical | IEEE 802.11p (5.9 GHz DSRC) |
|
||||
|
||||
## Relevance to Research
|
||||
ETSI ITS-G5 / CAM is the baseline broadcast protocol for V2V and V2I cooperative
|
||||
awareness in European ITS deployments. It directly underpins multi-agent vehicular
|
||||
coordination scenarios where agents (vehicles, RSUs) need real-time situational awareness
|
||||
without centralized orchestration — a direct comparison point for A2A-based agent
|
||||
discovery and task delegation in vehicular edge computing contexts.
|
||||
|
||||
## Download Instructions
|
||||
The standard PDF is freely available from ETSI:
|
||||
- Direct PDF: https://www.etsi.org/deliver/etsi_en/302600_302699/30263702/01.04.01_60/en_30263702v010401p.pdf
|
||||
|
||||
*Status: METADATA ONLY — PDF download blocked in sandbox environment (HTTPS proxy restriction)*
|
||||
*Retrieved: 2026-06-07*
|
||||
@@ -0,0 +1,42 @@
|
||||
# Gaba 2023 — Holochain DHT + IoT Security (IEEE Access)
|
||||
## Bibliographic Metadata
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| Authors | Gagandeep Singh Gaba, Gulshan Kumar, Tai-hoon Kim, Reji Thomas |
|
||||
| Title | Holochain: A Sustainable Distributed Ledger Technology for IoT Security and Privacy |
|
||||
| Journal | IEEE Access |
|
||||
| Year | 2023 |
|
||||
| Volume | 11 |
|
||||
| DOI | 10.1109/ACCESS.2023.3295589 |
|
||||
| IEEE Xplore | https://ieeexplore.ieee.org/document/10189589 |
|
||||
| Direct PDF | https://ieeexplore.ieee.org/stamp/stamp.jsp?arnumber=10189589 |
|
||||
| Open Access | Yes (IEEE Access is fully open access) |
|
||||
|
||||
## Abstract (Summary)
|
||||
This paper proposes using Holochain — a distributed hash table (DHT) based agent-centric
|
||||
architecture — as a security framework for IoT systems. Unlike blockchain, Holochain does not
|
||||
require global consensus; each agent maintains its own chain, enabling scalable, peer-validated
|
||||
data integrity. The paper addresses privacy, access control, and lightweight cryptographic
|
||||
verification suitable for resource-constrained IoT devices.
|
||||
|
||||
## Key Topics
|
||||
- Distributed Ledger Technology (DLT) for IoT
|
||||
- Holochain DHT agent-centric architecture
|
||||
- IoT security and privacy
|
||||
- Decentralized identity and access control
|
||||
- Lightweight cryptography for constrained devices
|
||||
|
||||
## Relevance to Research
|
||||
Directly relevant to research on decentralized multi-agent orchestration: Holochain's
|
||||
agent-centric DHT model parallels the Agent Card / peer-discovery model in A2A, and its
|
||||
security properties (per-agent chain, gossip validation) inform distributed trust models
|
||||
for IoT multi-agent systems.
|
||||
|
||||
## Download Instructions
|
||||
The full PDF is freely available (IEEE Access open access):
|
||||
- Visit: https://ieeexplore.ieee.org/stamp/stamp.jsp?arnumber=10189589
|
||||
- Or DOI: https://doi.org/10.1109/ACCESS.2023.3295589
|
||||
|
||||
*Status: METADATA ONLY — PDF download blocked in sandbox environment (HTTPS proxy restriction)*
|
||||
*Retrieved: 2026-06-07*
|
||||
@@ -0,0 +1,38 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<title>Ghosh 2025 - MAS with MCP/A2A (Metadata)</title>
|
||||
</head>
|
||||
<body>
|
||||
<h1>Multi-Agent Systems with MCP and A2A Protocols</h1>
|
||||
<h2>Bibliographic Metadata</h2>
|
||||
<table border="1" cellpadding="6">
|
||||
<tr><th>Field</th><th>Value</th></tr>
|
||||
<tr><td>Author(s)</td><td>Ghosh et al.</td></tr>
|
||||
<tr><td>Year</td><td>2025</td></tr>
|
||||
<tr><td>Type</td><td>Preprint / ResearchGate Publication</td></tr>
|
||||
<tr><td>ResearchGate URL</td><td>https://www.researchgate.net/publication/390919733</td></tr>
|
||||
<tr><td>Topic</td><td>Multi-Agent Systems (MAS) using Model Context Protocol (MCP) and Agent2Agent (A2A) Protocol</td></tr>
|
||||
<tr><td>Status</td><td>METADATA ONLY — Full HTML/PDF unavailable due to ResearchGate access restriction in sandbox environment</td></tr>
|
||||
</table>
|
||||
|
||||
<h2>Download Instructions</h2>
|
||||
<p>To obtain the full paper, visit the ResearchGate page directly:</p>
|
||||
<ul>
|
||||
<li>URL: <a href="https://www.researchgate.net/publication/390919733">https://www.researchgate.net/publication/390919733</a></li>
|
||||
<li>Login or create a free ResearchGate account if prompted.</li>
|
||||
<li>Click "Download full-text PDF" or "Request full-text".</li>
|
||||
</ul>
|
||||
|
||||
<h2>Relevance to Research</h2>
|
||||
<p>
|
||||
This preprint investigates the integration of the Model Context Protocol (MCP) and
|
||||
Agent2Agent (A2A) Protocol in Multi-Agent Systems (MAS). It is directly relevant to
|
||||
research on multi-agent orchestration, inter-agent communication standards, and
|
||||
protocol-based coordination in distributed AI systems.
|
||||
</p>
|
||||
|
||||
<p><em>Retrieved: 2026-06-07 | Access blocked in automated environment</em></p>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,92 @@
|
||||
# Agent2Agent (A2A) Protocol
|
||||
|
||||
[](https://pypi.org/project/a2a-sdk)
|
||||
[](LICENSE)
|
||||
|
||||
<!-- markdownlint-disable MD041 -->
|
||||
<div style="text-align: center;">
|
||||
<h1>Agent2Agent (A2A) Protocol</h1>
|
||||
</div>
|
||||
|
||||
**An open protocol enabling communication and interoperability between opaque agentic applications.**
|
||||
|
||||
The Agent2Agent (A2A) protocol addresses a critical challenge in the AI landscape: enabling gen AI agents, built on diverse frameworks by different companies running on separate servers, to communicate and collaborate effectively - as agents, not just as tools. A2A aims to provide a common language for agents, fostering a more interconnected, powerful, and innovative AI ecosystem.
|
||||
|
||||
With A2A, agents can:
|
||||
|
||||
- Discover each other's capabilities.
|
||||
- Negotiate interaction modalities (text, forms, media).
|
||||
- Securely collaborate on long-running tasks.
|
||||
- Operate without exposing their internal state, memory, or tools.
|
||||
|
||||
## DeepLearning.AI Course
|
||||
|
||||
Join this short course on [A2A: The Agent2Agent Protocol](https://goo.gle/dlai-a2a), built in partnership with Google Cloud and IBM Research.
|
||||
|
||||
**What you'll learn:**
|
||||
|
||||
- **Make agents A2A-compliant:** Expose agents built with frameworks like Google ADK, LangGraph, or BeeAI as A2A servers.
|
||||
- **Connect agents:** Create A2A clients from scratch or using integrations to connect to A2A-compliant agents.
|
||||
- **Orchestrate workflows:** Build sequential and hierarchical workflows of A2A-compliant agents.
|
||||
- **Multi-agent systems:** Build a healthcare multi-agent system using different frameworks and see how A2A enables collaboration.
|
||||
- **A2A and MCP:** Learn how A2A complements MCP by enabling agents to collaborate with each other.
|
||||
|
||||
## Why A2A?
|
||||
|
||||
As AI agents become more prevalent, their ability to interoperate is crucial for building complex, multi-functional applications. A2A aims to:
|
||||
|
||||
- **Break Down Silos:** Connect agents across different ecosystems.
|
||||
- **Enable Complex Collaboration:** Allow specialized agents to work together on tasks that a single agent cannot handle alone.
|
||||
- **Promote Open Standards:** Foster a community-driven approach to agent communication, encouraging innovation and broad adoption.
|
||||
- **Preserve Opacity:** Allow agents to collaborate without needing to share internal memory, proprietary logic, or specific tool implementations, enhancing security and protecting intellectual property.
|
||||
|
||||
### Key Features
|
||||
|
||||
- **Standardized Communication:** JSON-RPC 2.0 over HTTP(S).
|
||||
- **Agent Discovery:** Via "Agent Cards" detailing capabilities and connection info.
|
||||
- **Flexible Interaction:** Supports synchronous request/response, streaming (SSE), and asynchronous push notifications.
|
||||
- **Rich Data Exchange:** Handles text, files, and structured JSON data.
|
||||
- **Enterprise-Ready:** Designed with security, authentication, and observability in mind.
|
||||
|
||||
## Getting Started
|
||||
|
||||
- **Explore the Documentation:** Visit the [Agent2Agent Protocol Documentation Site](https://a2a-protocol.org) for a complete overview, the full protocol specification, tutorials, and guides.
|
||||
- **View the Specification:** [A2A Protocol Specification](https://a2a-protocol.org/latest/specification/)
|
||||
- Use the SDKs:
|
||||
- [A2A Python SDK](https://github.com/a2aproject/a2a-python) `pip install a2a-sdk`
|
||||
- [A2A Go SDK](https://github.com/a2aproject/a2a-go) `go get github.com/a2aproject/a2a-go`
|
||||
- [A2A JS SDK](https://github.com/a2aproject/a2a-js) `npm install @a2a-js/sdk`
|
||||
- [A2A Java SDK](https://github.com/a2aproject/a2a-java) using maven
|
||||
- [A2A .NET SDK](https://github.com/a2aproject/a2a-dotnet) using NuGet `dotnet add package A2A`
|
||||
- Use our [samples](https://github.com/a2aproject/a2a-samples) to see A2A in action
|
||||
|
||||
## Contributing
|
||||
|
||||
We welcome community contributions to enhance and evolve the A2A protocol!
|
||||
|
||||
- **Questions & Discussions:** Join our [GitHub Discussions](https://github.com/a2aproject/A2A/discussions).
|
||||
- **Issues & Feedback:** Report issues or suggest improvements via [GitHub Issues](https://github.com/a2aproject/A2A/issues).
|
||||
- **Contribution Guide:** See our [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to contribute.
|
||||
- **Private Feedback:** Use this [Google Form](https://goo.gle/a2a-feedback).
|
||||
- **Partner Program:** Google Cloud customers can join our partner program via this [form](https://goo.gle/a2a-partner).
|
||||
|
||||
## What's next
|
||||
|
||||
### Protocol Enhancements
|
||||
|
||||
- **Agent Discovery:**
|
||||
- Formalize inclusion of authorization schemes and optional credentials directly within the `AgentCard`.
|
||||
- **Agent Collaboration:**
|
||||
- Investigate a `QuerySkill()` method for dynamically checking unsupported or unanticipated skills.
|
||||
- **Task Lifecycle & UX:**
|
||||
- Support for dynamic UX negotiation _within_ a task (e.g., agent adding audio/video mid-conversation).
|
||||
- **Client Methods & Transport:**
|
||||
- Explore extending support to client-initiated methods (beyond task management).
|
||||
- Improvements to streaming reliability and push notification mechanisms.
|
||||
|
||||
## About
|
||||
|
||||
The A2A Protocol is an open source project under the Linux Foundation, contributed by Google. It is licensed under the [Apache License 2.0](LICENSE) and is open to contributions from the community.
|
||||
|
||||
---
|
||||
*Source: https://github.com/a2aproject/A2A — Retrieved 2026-06-07*
|
||||
@@ -0,0 +1,31 @@
|
||||
# Model Context Protocol (MCP)
|
||||
|
||||
_Just heard of MCP and not sure where to start? Check out our [documentation website](https://modelcontextprotocol.io)._
|
||||
|
||||
This repo contains the:
|
||||
|
||||
- MCP specification
|
||||
- MCP protocol schema
|
||||
- Official MCP documentation
|
||||
|
||||
The schema is [defined in TypeScript](schema/2025-11-25/schema.ts) first, but
|
||||
[made available as JSON Schema](schema/2025-11-25/schema.json) as well, for wider
|
||||
compatibility.
|
||||
|
||||
The official MCP documentation is built using Mintlify and available at
|
||||
[modelcontextprotocol.io](https://modelcontextprotocol.io).
|
||||
|
||||
## Authors
|
||||
|
||||
The Model Context Protocol was created by David Soria Parra ([@dsp](https://github.com/dsp)) and Justin Spahr-Summers ([@jspahrsummers](https://github.com/jspahrsummers)).
|
||||
|
||||
## Contributing
|
||||
|
||||
See [CONTRIBUTING.md](./CONTRIBUTING.md).
|
||||
|
||||
## License
|
||||
|
||||
This project is licensed under the [MIT License](LICENSE).
|
||||
|
||||
---
|
||||
*Source: https://raw.githubusercontent.com/modelcontextprotocol/specification/main/README.md — Retrieved 2026-06-07*
|
||||
@@ -0,0 +1,418 @@
|
||||
MQTT Version 5.0
|
||||
OASIS Standard
|
||||
07 March 2019
|
||||
|
||||
NOTE: This file contains the text content extracted from the PDF at:
|
||||
https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.pdf
|
||||
|
||||
Specification URIs:
|
||||
https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.docx (Authoritative)
|
||||
https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html
|
||||
https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.pdf
|
||||
|
||||
Technical Committee: OASIS Message Queuing Telemetry Transport (MQTT) TC
|
||||
Editors: Andrew Banks (IBM), Ed Briggs (Microsoft), Ken Borgendale (IBM), Rahul Gupta (IBM)
|
||||
|
||||
Abstract:
|
||||
MQTT is a Client Server publish/subscribe messaging transport protocol. It is light weight, open,
|
||||
simple, and designed to be easy to implement. These characteristics make it ideal for use in many
|
||||
situations, including constrained environments such as Machine to Machine (M2M) and Internet
|
||||
of Things (IoT) contexts where a small code footprint is required and/or network bandwidth is
|
||||
at a premium.
|
||||
|
||||
The protocol runs over TCP/IP, or over other network protocols that provide ordered, lossless,
|
||||
bidirectional connections. Its features include:
|
||||
- Use of the publish/subscribe message pattern which provides one-to-many message
|
||||
distribution and decoupling of applications.
|
||||
- A messaging transport that is agnostic to the content of the payload.
|
||||
- Three qualities of service for message delivery:
|
||||
o "At most once": messages delivered according to best efforts; message loss can occur.
|
||||
o "At least once": messages assured to arrive but duplicates can occur.
|
||||
o "Exactly once": messages assured to arrive exactly once.
|
||||
- A small transport overhead and protocol exchanges minimized to reduce network traffic.
|
||||
- A mechanism to notify interested parties when an abnormal disconnection occurs.
|
||||
|
||||
Copyright © OASIS Open 2019. All Rights Reserved.
|
||||
|
||||
================================================================================
|
||||
Table of Contents
|
||||
================================================================================
|
||||
|
||||
1 Introduction
|
||||
1.1 Organization of the MQTT specification
|
||||
1.2 Terminology
|
||||
1.3 Normative references
|
||||
1.4 Non-normative references
|
||||
1.5 Data representation
|
||||
1.5.1 Bits
|
||||
1.5.2 Two Byte Integer
|
||||
1.5.3 Four Byte Integer
|
||||
1.5.4 UTF-8 Encoded String
|
||||
1.5.5 Variable Byte Integer
|
||||
1.5.6 Binary Data
|
||||
1.5.7 UTF-8 String Pair
|
||||
1.6 Security
|
||||
1.7 Editing convention
|
||||
1.8 Change history
|
||||
|
||||
2 MQTT Control Packet format
|
||||
2.1 Structure of an MQTT Control Packet
|
||||
2.1.1 Fixed Header
|
||||
2.1.2 MQTT Control Packet type
|
||||
2.1.3 Flags
|
||||
2.1.4 Remaining Length
|
||||
2.2 Variable Header
|
||||
2.2.1 Packet Identifier
|
||||
2.2.2 Properties
|
||||
2.3 Payload
|
||||
2.4 Reason Code
|
||||
|
||||
3 MQTT Control Packets
|
||||
3.1 CONNECT – Connection Request
|
||||
3.2 CONNACK – Connect acknowledgement
|
||||
3.3 PUBLISH – Publish message
|
||||
3.4 PUBACK – Publish acknowledgement (QoS 1)
|
||||
3.5 PUBREC – Publish received (QoS 2 delivery part 1)
|
||||
3.6 PUBREL – Publish release (QoS 2 delivery part 2)
|
||||
3.7 PUBCOMP – Publish complete (QoS 2 delivery part 3)
|
||||
3.8 SUBSCRIBE – Subscribe request
|
||||
3.9 SUBACK – Subscribe acknowledgement
|
||||
3.10 UNSUBSCRIBE – Unsubscribe request
|
||||
3.11 UNSUBACK – Unsubscribe acknowledgement
|
||||
3.12 PINGREQ – PING request
|
||||
3.13 PINGRESP – PING response
|
||||
3.14 DISCONNECT – Disconnect notification
|
||||
3.15 AUTH – Authentication exchange
|
||||
|
||||
4 Operational behavior
|
||||
4.1 Session State
|
||||
4.2 Network Connections
|
||||
4.3 Quality of Service levels and protocol flows
|
||||
4.4 Message delivery retry
|
||||
4.5 Message receipt
|
||||
4.6 Message ordering
|
||||
4.7 Topic Names and Topic Filters
|
||||
4.8 Subscriptions
|
||||
4.9 Flow Control
|
||||
4.10 Request / Response
|
||||
4.11 Server redirection
|
||||
4.12 Enhanced authentication
|
||||
4.13 Handling errors
|
||||
|
||||
5 Security (non-normative)
|
||||
6 Using WebSocket as a network transport
|
||||
7 Conformance
|
||||
Appendix A. Summary of new features in MQTT v5.0
|
||||
Appendix B. Mandatory normative statements
|
||||
Appendix C. Non-normative bibliographic references
|
||||
|
||||
================================================================================
|
||||
1 Introduction
|
||||
================================================================================
|
||||
|
||||
1.1 Organization of the MQTT specification
|
||||
|
||||
Chapter 1 - Introduction
|
||||
Chapter 2 - MQTT Control Packet format
|
||||
Chapter 3 - MQTT Control Packets
|
||||
Chapter 4 - Operational behavior
|
||||
Chapter 5 - Security
|
||||
Chapter 6 - Using WebSocket as a network transport
|
||||
Chapter 7 - Conformance Targets
|
||||
|
||||
1.2 Terminology
|
||||
|
||||
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
|
||||
"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this specification are to be
|
||||
interpreted as described in IETF RFC 2119.
|
||||
|
||||
Key terms:
|
||||
- **Application Message**: The data carried by the MQTT protocol across the network
|
||||
- **Client**: A program or device that uses MQTT. A Client always establishes the Network Connection
|
||||
to the Server. It can Publish Application Messages, Subscribe/Unsubscribe to request messages.
|
||||
- **Server**: A program or device that acts as an intermediary between Clients which publish
|
||||
Application Messages and Clients which have made Subscriptions.
|
||||
- **Session**: A stateful interaction between a Client and a Server. Can span more than one Network Connection.
|
||||
- **Subscription**: A Subscription comprises a Topic Filter and a maximum QoS. Associated with a single Session.
|
||||
- **Shared Subscription**: A Subscription with multiple Clients to allow load balancing.
|
||||
- **Wildcard Subscription**: A Subscription using a Topic Filter containing a wildcard character.
|
||||
- **Topic Name**: A label attached to an Application Message which is matched against Subscriptions.
|
||||
- **Topic Filter**: An expression in a Subscription to indicate matching Topic Names.
|
||||
- **MQTT Control Packet**: A packet of information sent across the Network Connection. The MQTT
|
||||
specification defines fifteen different types.
|
||||
- **Malformed Packet**: A Control Packet that cannot be parsed according to this specification.
|
||||
- **Protocol Error**: An error discovered after packet parsing which does not conform to the specification.
|
||||
- **Will Message**: An Application Message which is published by the Server after the Network
|
||||
Connection is closed in cases where the Network Connection is not closed normally.
|
||||
- **Disallowed Unicode code point**: Code points defined in section 1.5.4 which should not appear
|
||||
in a UTF-8 Encoded String.
|
||||
|
||||
1.5 Data representation
|
||||
|
||||
1.5.2 Two Byte Integer
|
||||
Two Byte Integer values are 16-bit unsigned integers in big-endian order: high order byte followed
|
||||
by low order byte. This means a 16-bit word is presented on the network as Most Significant Byte
|
||||
(MSB), followed by Least Significant Byte (LSB).
|
||||
|
||||
1.5.3 Four Byte Integer
|
||||
Four Byte Integer values are 32-bit unsigned integers in big-endian order.
|
||||
|
||||
1.5.4 UTF-8 Encoded String
|
||||
Text fields within the MQTT Control Packets are encoded as UTF-8 strings.
|
||||
- Maximum size: 65,535 bytes
|
||||
- A UTF-8 Encoded String MUST NOT include an encoding of the null character U+0000.
|
||||
- A UTF-8 encoded sequence 0xEF 0xBB 0xBF is always interpreted as U+FEFF (ZERO WIDTH
|
||||
NO-BREAK SPACE) wherever it appears in a string; it MUST NOT be skipped over or stripped
|
||||
off by a packet receiver.
|
||||
|
||||
1.5.5 Variable Byte Integer
|
||||
The Variable Byte Integer uses a scheme where the low seven bits of each byte encode the data,
|
||||
and the high bit indicates whether there are bytes following in the representation.
|
||||
- 1 byte: 0 to 127
|
||||
- 2 bytes: 128 to 16,383
|
||||
- 3 bytes: 16,384 to 2,097,151
|
||||
- 4 bytes: 2,097,152 to 268,435,455
|
||||
|
||||
================================================================================
|
||||
2 MQTT Control Packet format
|
||||
================================================================================
|
||||
|
||||
2.1.2 MQTT Control Packet type
|
||||
|
||||
| Name | Value | Direction of flow | Description |
|
||||
|----------|-------|----------------------|--------------------------|
|
||||
| CONNECT | 1 | Client to Server | Connection request |
|
||||
| CONNACK | 2 | Server to Client | Connect acknowledgement |
|
||||
| PUBLISH | 3 | Client to Server or | Publish message |
|
||||
| | | Server to Client | |
|
||||
| PUBACK | 4 | Client to Server or | Publish acknowledgement |
|
||||
| | | Server to Client | (QoS 1) |
|
||||
| PUBREC | 5 | Client to Server or | Publish received |
|
||||
| | | Server to Client | (QoS 2 delivery part 1) |
|
||||
| PUBREL | 6 | Client to Server or | Publish release |
|
||||
| | | Server to Client | (QoS 2 delivery part 2) |
|
||||
| PUBCOMP | 7 | Client to Server or | Publish complete |
|
||||
| | | Server to Client | (QoS 2 delivery part 3) |
|
||||
| SUBSCRIBE| 8 | Client to Server | Subscribe request |
|
||||
| SUBACK | 9 | Server to Client | Subscribe acknowledgement|
|
||||
| UNSUBSCRIBE|10 | Client to Server | Unsubscribe request |
|
||||
| UNSUBACK | 11 | Server to Client | Unsubscribe acknowledge |
|
||||
| PINGREQ | 12 | Client to Server | PING request |
|
||||
| PINGRESP | 13 | Server to Client | PING response |
|
||||
| DISCONNECT|14 | Client to Server or | Disconnect notification |
|
||||
| | | Server to Client | |
|
||||
| AUTH | 15 | Client to Server or | Authentication exchange |
|
||||
| | | Server to Client | |
|
||||
|
||||
2.2.2 Properties
|
||||
|
||||
Properties were introduced in MQTT v5.0 to provide extensibility.
|
||||
Each property has an identifier encoded as a Variable Byte Integer.
|
||||
|
||||
Key properties (by packet type):
|
||||
- Payload Format Indicator (0x01): PUBLISH
|
||||
- Message Expiry Interval (0x02): PUBLISH
|
||||
- Content Type (0x03): PUBLISH
|
||||
- Response Topic (0x08): PUBLISH
|
||||
- Correlation Data (0x09): PUBLISH
|
||||
- Subscription Identifier (0x0B): PUBLISH, SUBSCRIBE
|
||||
- Session Expiry Interval (0x11): CONNECT, CONNACK, DISCONNECT
|
||||
- Assigned Client Identifier (0x12): CONNACK
|
||||
- Server Keep Alive (0x13): CONNACK
|
||||
- Authentication Method (0x15): CONNECT, CONNACK, AUTH
|
||||
- Authentication Data (0x16): CONNECT, CONNACK, AUTH
|
||||
- Request Problem Information (0x17): CONNECT
|
||||
- Will Delay Interval (0x18): Will Properties
|
||||
- Request Response Information (0x19): CONNECT
|
||||
- Response Information (0x1A): CONNACK
|
||||
- Server Reference (0x1C): CONNACK, DISCONNECT
|
||||
- Reason String (0x1F): CONNACK, PUBACK, PUBREC, PUBREL, PUBCOMP,
|
||||
SUBACK, UNSUBACK, DISCONNECT, AUTH
|
||||
- Receive Maximum (0x21): CONNECT, CONNACK
|
||||
- Topic Alias Maximum (0x22): CONNECT, CONNACK
|
||||
- Topic Alias (0x23): PUBLISH
|
||||
- Maximum QoS (0x24): CONNACK
|
||||
- Retain Available (0x25): CONNACK
|
||||
- User Property (0x26): All packets
|
||||
- Maximum Packet Size (0x27): CONNECT, CONNACK
|
||||
- Wildcard Subscription Available (0x28): CONNACK
|
||||
- Subscription Identifier Available (0x29): CONNACK
|
||||
- Shared Subscription Available (0x2A): CONNACK
|
||||
|
||||
2.4 Reason Code
|
||||
|
||||
New in MQTT v5.0. Reason Codes communicate the result of an operation.
|
||||
|
||||
| Dec | Hex | Name | Packets |
|
||||
|-----|------|-------------------------------|--------------------------------------|
|
||||
| 0 | 0x00 | Success/Normal disconnection | CONNACK, PUBACK, PUBREC, PUBREL, |
|
||||
| | | | PUBCOMP, UNSUBACK, AUTH, DISCONNECT |
|
||||
| 1 | 0x01 | Granted QoS 1 | SUBACK |
|
||||
| 2 | 0x02 | Granted QoS 2 | SUBACK |
|
||||
| 4 | 0x04 | Disconnect with Will Message | DISCONNECT |
|
||||
| 16 | 0x10 | No matching subscribers | PUBACK, PUBREC |
|
||||
| 17 | 0x11 | No subscription found | UNSUBACK |
|
||||
| 24 | 0x18 | Continue authentication | AUTH |
|
||||
| 25 | 0x19 | Re-authenticate | AUTH |
|
||||
| 128 | 0x80 | Unspecified error | CONNACK, PUBACK, PUBREC, SUBACK, |
|
||||
| | | | UNSUBACK, DISCONNECT |
|
||||
| 129 | 0x81 | Malformed Packet | CONNACK, DISCONNECT |
|
||||
| 130 | 0x82 | Protocol Error | CONNACK, DISCONNECT |
|
||||
| 131 | 0x83 | Implementation specific error | CONNACK, PUBACK, PUBREC, SUBACK, |
|
||||
| | | | UNSUBACK, DISCONNECT |
|
||||
| 132 | 0x84 | Unsupported Protocol Version | CONNACK |
|
||||
| 133 | 0x85 | Client Identifier not valid | CONNACK |
|
||||
| 134 | 0x86 | Bad User Name or Password | CONNACK |
|
||||
| 135 | 0x87 | Not authorized | CONNACK, PUBACK, PUBREC, SUBACK, |
|
||||
| | | | UNSUBACK, DISCONNECT |
|
||||
| 136 | 0x88 | Server unavailable | CONNACK |
|
||||
| 137 | 0x89 | Server busy | CONNACK, DISCONNECT |
|
||||
| 144 | 0x90 | Topic Name invalid | CONNACK, PUBACK, PUBREC, DISCONNECT |
|
||||
| 145 | 0x91 | Packet Identifier in use | PUBACK, PUBREC, SUBACK, UNSUBACK |
|
||||
| 146 | 0x92 | Packet Identifier not found | PUBREL, PUBCOMP |
|
||||
| 147 | 0x93 | Receive Maximum exceeded | DISCONNECT |
|
||||
| 148 | 0x94 | Topic Alias invalid | DISCONNECT |
|
||||
| 149 | 0x95 | Packet too large | CONNACK, DISCONNECT |
|
||||
| 151 | 0x97 | Quota exceeded | CONNACK, PUBACK, PUBREC, SUBACK, |
|
||||
| | | | DISCONNECT |
|
||||
| 153 | 0x99 | Payload format invalid | CONNACK, PUBACK, PUBREC, DISCONNECT |
|
||||
| 154 | 0x9A | Retain not supported | CONNACK, DISCONNECT |
|
||||
| 155 | 0x9B | QoS not supported | CONNACK, DISCONNECT |
|
||||
| 156 | 0x9C | Use another server | CONNACK, DISCONNECT |
|
||||
| 157 | 0x9D | Server moved | CONNACK, DISCONNECT |
|
||||
| 158 | 0x9E | Shared Subscriptions not supported | CONNACK, SUBACK, DISCONNECT |
|
||||
| 159 | 0x9F | Connection rate exceeded | CONNACK, DISCONNECT |
|
||||
| 160 | 0xA0 | Maximum connect time | DISCONNECT |
|
||||
| 161 | 0xA1 | Subscription Identifiers not supported | CONNACK, SUBACK, DISCONNECT |
|
||||
| 162 | 0xA2 | Wildcard Subscriptions not supported | CONNACK, SUBACK, DISCONNECT |
|
||||
|
||||
================================================================================
|
||||
3 MQTT Control Packets (Key Sections)
|
||||
================================================================================
|
||||
|
||||
3.1 CONNECT – Connection Request
|
||||
|
||||
3.1.2.3 Connect Flags
|
||||
Connect Flags byte contains parameters specifying the behavior of the MQTT Connection:
|
||||
- Bit 7: User Name Flag
|
||||
- Bit 6: Password Flag
|
||||
- Bit 5: Will Retain
|
||||
- Bits 4-3: Will QoS
|
||||
- Bit 2: Will Flag
|
||||
- Bit 1: Clean Start
|
||||
- Bit 0: Reserved (MUST be 0)
|
||||
|
||||
3.1.2.4 Clean Start
|
||||
Bit 1 of Connect Flags. If set to 1, the Client and Server MUST discard any existing Session
|
||||
and start a new Session. If set to 0, the Server MUST resume communications based on the
|
||||
state from any existing Session.
|
||||
|
||||
3.1.2.11.3 Receive Maximum
|
||||
Two Byte Integer. Client uses this to limit the number of QoS 1 and QoS 2 publications
|
||||
that it is willing to process concurrently. Default: 65,535.
|
||||
|
||||
3.1.2.11.2 Session Expiry Interval
|
||||
Four Byte Integer. Represents the Session Expiry Interval in seconds. If 0 or absent: Session
|
||||
ends when Network Connection is closed. If 0xFFFFFFFF: Session does not expire.
|
||||
|
||||
3.3 PUBLISH – Publish message
|
||||
|
||||
3.3.1.1 DUP flag: Bit 3. If set to 0, indicates first delivery of this PUBLISH packet.
|
||||
3.3.1.2 QoS level: Bits 2-1. Quality of Service level:
|
||||
- 0b00 (0): At most once delivery
|
||||
- 0b01 (1): At least once delivery
|
||||
- 0b10 (2): Exactly once delivery
|
||||
- 0b11 (3): MUST NOT be used
|
||||
3.3.1.3 RETAIN flag: Bit 0. If set to 1, Application Message is stored by the Server.
|
||||
|
||||
3.3.2.1 Topic Name: MUST NOT contain wildcard characters.
|
||||
3.3.2.2 Packet Identifier: Only present for QoS 1 and QoS 2.
|
||||
|
||||
3.8 SUBSCRIBE – Subscribe request
|
||||
|
||||
3.8.4 SUBSCRIBE Payload:
|
||||
Each Subscription consists of:
|
||||
- Topic Filter (UTF-8 string)
|
||||
- Subscription Options byte:
|
||||
- Bits 0-1: Maximum QoS
|
||||
- Bit 2: No Local (don't receive own publishes)
|
||||
- Bit 3: Retain As Published
|
||||
- Bits 4-5: Retain Handling
|
||||
- 0: Send retained at subscribe
|
||||
- 1: Send only if new subscription
|
||||
- 2: Do not send retained at subscribe
|
||||
|
||||
================================================================================
|
||||
4 Operational Behavior (Key Sections)
|
||||
================================================================================
|
||||
|
||||
4.3 Quality of Service levels and protocol flows
|
||||
|
||||
4.3.1 QoS 0: At most once delivery
|
||||
The sender sends the PUBLISH packet.
|
||||
No response, no retry.
|
||||
|
||||
4.3.2 QoS 1: At least once delivery
|
||||
Sender -> Receiver: PUBLISH (Packet Identifier X)
|
||||
Receiver -> Sender: PUBACK (Packet Identifier X)
|
||||
If Sender does not receive PUBACK, it retransmits with DUP=1.
|
||||
|
||||
4.3.3 QoS 2: Exactly once delivery
|
||||
Sender -> Receiver: PUBLISH (Packet Identifier X)
|
||||
Receiver -> Sender: PUBREC (Packet Identifier X)
|
||||
Sender -> Receiver: PUBREL (Packet Identifier X)
|
||||
Receiver -> Sender: PUBCOMP (Packet Identifier X)
|
||||
|
||||
4.7 Topic Names and Topic Filters
|
||||
|
||||
Topic level separator: '/' (forward slash, U+002F)
|
||||
Wildcards:
|
||||
- '#' (Number sign, U+0023): Multi-level wildcard. MUST be the last character in the Topic
|
||||
Filter, preceded only by a separator. Example: "sport/#"
|
||||
- '+' (Plus sign, U+002B): Single-level wildcard. Example: "sport/+/player1"
|
||||
|
||||
Topic Names and Topic Filters beginning with '$' are reserved for Server-internal use.
|
||||
A Subscription Topic Filter starting with '$' MUST NOT be matched by a Topic Name beginning
|
||||
with a topic level not starting with '$'.
|
||||
|
||||
4.9 Flow Control (NEW in v5.0)
|
||||
- Client sends CONNECT with Receive Maximum value (e.g., 10)
|
||||
- Server tracks how many PUBLISH packets with QoS>0 are unacknowledged
|
||||
- Server MUST NOT send more QoS 1 or QoS 2 PUBLISH packets to the Client than allowed
|
||||
by the Receive Maximum
|
||||
|
||||
4.10 Request / Response (NEW in v5.0)
|
||||
MQTT v5.0 includes a Request/Response pattern:
|
||||
- Requestor sends PUBLISH with Response Topic and optional Correlation Data
|
||||
- Responder publishes to Response Topic with same Correlation Data
|
||||
- Enables point-to-point communication without pre-knowledge of each other
|
||||
|
||||
4.12 Enhanced authentication (NEW in v5.0)
|
||||
Extended authentication allows the use of challenge/response style authentication:
|
||||
1. Client sends CONNECT with Authentication Method property
|
||||
2. Server sends AUTH (0x18 Continue authentication) with Authentication Data
|
||||
3. Client responds with AUTH containing more Authentication Data
|
||||
4. Exchange continues until Server sends CONNACK (success or failure)
|
||||
|
||||
================================================================================
|
||||
Appendix A. Summary of new features in MQTT v5.0
|
||||
================================================================================
|
||||
|
||||
New features compared to MQTT v3.1.1:
|
||||
|
||||
1. **Session expiry**: Separate control of when session state should be discarded
|
||||
2. **Message expiry**: Expiry time for application messages
|
||||
3. **Reason codes on all ACKs**: All response packets include a Reason Code
|
||||
4. **Reason string**: Optional human-readable reason string on most packets
|
||||
5. **Server disconnect**: Server can now send DISCONNECT to indicate why the connection was closed
|
||||
6. **Payload format and content type**: Description of application message content
|
||||
7. **Request/Response**: Pattern support with Response Topic and Correlation Data
|
||||
8. **Shared Subscriptions**: Allows load-balanced message processing
|
||||
9. **Subscription identifier**: Client can specify an identifier in SUBSCRIBE
|
||||
10. **Topic alias**: Reduces overhead by using integer instead of Topic Name
|
||||
11. **Flow control**: Client and Server can specify how many simultaneous messages they can handle
|
||||
12. **User properties**: On most packets, arbitrary name-value string pairs
|
||||
13. **Maximum packet size**: Client and Server can specify maximum packet size they can handle
|
||||
14. **Server reference**: CONNACK and DISCONNECT can indicate another Server to use
|
||||
15. **Enhanced authentication**: Challenge/response style authentication
|
||||
16. **Will delay**: Delay publication of Will Messages at end of session
|
||||
@@ -0,0 +1,123 @@
|
||||
# OpenTelemetry Overview
|
||||
|
||||
> Source: https://raw.githubusercontent.com/open-telemetry/opentelemetry-specification/main/specification/overview.md
|
||||
> Downloaded: 2026-06-07
|
||||
|
||||
This document provides an overview of the OpenTelemetry project and defines important fundamental terms.
|
||||
|
||||
## OpenTelemetry Client Architecture
|
||||
|
||||
At the highest architectural level, OpenTelemetry clients are organized into **signals**. Each signal provides a specialized form of observability. For example, tracing, metrics, and baggage are three separate signals. Signals share a common subsystem – **context propagation** – but they function independently from each other.
|
||||
|
||||
Each signal consists of four types of packages: API, SDK, Semantic Conventions, and Contrib.
|
||||
|
||||
### API
|
||||
|
||||
API packages consist of the cross-cutting public interfaces used for instrumentation. Any portion of an OpenTelemetry client which is imported into third-party libraries and application code is considered part of the API.
|
||||
|
||||
### SDK
|
||||
|
||||
The SDK is the implementation of the API provided by the OpenTelemetry project. Within an application, the SDK is installed and managed by the application owner.
|
||||
|
||||
### Semantic Conventions
|
||||
|
||||
The **Semantic Conventions** define the keys and values which describe commonly observed concepts, protocols, and operations used by applications.
|
||||
|
||||
Semantic Conventions are now located in their own repository:
|
||||
https://github.com/open-telemetry/semantic-conventions
|
||||
|
||||
### Contrib Packages
|
||||
|
||||
The OpenTelemetry project maintains integrations with popular OSS projects. **API Contrib** refers to packages which depend solely upon the API; **SDK Contrib** refers to packages which also depend upon the SDK.
|
||||
|
||||
## Tracing Signal
|
||||
|
||||
A distributed trace is a set of events, triggered as a result of a single logical operation, consolidated across various components of an application.
|
||||
|
||||
### Traces
|
||||
|
||||
**Traces** in OpenTelemetry are defined implicitly by their **Spans**. A **Trace** can be thought of as a directed acyclic graph (DAG) of **Spans**, where the edges between **Spans** are defined as parent/child relationship.
|
||||
|
||||
```
|
||||
Causal relationships between Spans in a single Trace
|
||||
|
||||
[Span A] (the root span)
|
||||
|
|
||||
+------+------+
|
||||
| |
|
||||
[Span B] [Span C]
|
||||
| |
|
||||
[Span D] +---+-------+
|
||||
| |
|
||||
[Span E] [Span F]
|
||||
```
|
||||
|
||||
### Spans
|
||||
|
||||
A span represents an operation within a transaction. Each **Span** encapsulates:
|
||||
|
||||
- An operation name
|
||||
- A start and finish timestamp
|
||||
- **Attributes**: A list of key-value pairs
|
||||
- A set of zero or more **Events**
|
||||
- Parent's **Span** identifier
|
||||
- **Links** to zero or more causally-related **Spans**
|
||||
- **SpanContext** information
|
||||
|
||||
### SpanContext
|
||||
|
||||
Represents all the information that identifies **Span** in the **Trace**:
|
||||
|
||||
- **TraceId** - 16 randomly generated bytes, worldwide unique
|
||||
- **SpanId** - 8 randomly generated bytes, globally unique
|
||||
- **TraceFlags** - 1 byte bitmap (includes sampling bit)
|
||||
- **Tracestate** - tracing-system specific context in key-value pairs
|
||||
|
||||
## Metric Signal
|
||||
|
||||
OpenTelemetry allows recording raw measurements or metrics with predefined aggregations and a set of attributes.
|
||||
|
||||
### Instruments
|
||||
|
||||
Instruments are used to report `Measurement`s, identified by a name, kind, description, and unit of values. Types include counters, gauges, and histograms. Instruments can be synchronous or asynchronous.
|
||||
|
||||
## Log Signal
|
||||
|
||||
### Data model
|
||||
|
||||
[Log Data Model](logs/data-model.md) defines how logs and events are understood by OpenTelemetry.
|
||||
|
||||
## Baggage Signal
|
||||
|
||||
OpenTelemetry provides a simple mechanism for propagating name/value pairs, called `Baggage`. `Baggage` is intended for indexing observability events in one service with attributes provided by a prior service in the same transaction.
|
||||
|
||||
## Resources
|
||||
|
||||
`Resource` captures information about the entity for which telemetry is recorded. For example, metrics exposed by a Kubernetes container can be linked to a resource that specifies the cluster, namespace, pod, and container name.
|
||||
|
||||
## Context Propagation
|
||||
|
||||
All of OpenTelemetry cross-cutting concerns share an underlying `Context` mechanism for storing state and accessing data across the lifespan of a distributed transaction.
|
||||
|
||||
## Propagators
|
||||
|
||||
OpenTelemetry uses `Propagators` to serialize and deserialize cross-cutting concern values such as `Span`s and `Baggage`.
|
||||
|
||||
The Propagators API currently defines one `Propagator` type:
|
||||
|
||||
- `TextMapPropagator` injects values into and extracts values from carriers as text.
|
||||
|
||||
## Collector
|
||||
|
||||
The OpenTelemetry Collector is a set of components that can collect traces, metrics and other telemetry data from processes instrumented by OpenTelemetry or other monitoring/tracing libraries (Jaeger, Prometheus, etc.), do aggregation and smart sampling, and export traces and metrics to one or more monitoring/tracing backends.
|
||||
|
||||
The OpenTelemetry Collector has two primary modes of operation: **Agent** (a daemon running locally with the application) and **Collector** (a standalone running service).
|
||||
|
||||
## Instrumentation Libraries
|
||||
|
||||
A library that enables OpenTelemetry observability for another library is called an **Instrumentation Library**.
|
||||
|
||||
For instrumentation hosted in OpenTelemetry repositories, the recommendation is to prefix packages with "opentelemetry-instrumentation", followed by the instrumented library name. Examples:
|
||||
|
||||
* opentelemetry-instrumentation-flask (Python)
|
||||
* @opentelemetry/instrumentation-grpc (JavaScript)
|
||||
@@ -0,0 +1,135 @@
|
||||
# Protobuf Editions Design: Features
|
||||
|
||||
**Author:** [@haberman](https://github.com/haberman), [@fowles](https://github.com/fowles)
|
||||
|
||||
**Approved:** 2022-10-13
|
||||
|
||||
A proposal to use custom options as our way of defining and representing features.
|
||||
|
||||
## Background
|
||||
|
||||
The [Protobuf Editions](what-are-protobuf-editions.md) project uses "editions" to allow Protobuf to safely evolve over time. An edition is formally a set of "features" with a default value per feature. Features define the specific points of change and evolution on a per entity basis within a .proto file.
|
||||
|
||||
## Sample Usage
|
||||
|
||||
```
|
||||
edition = "2023";
|
||||
|
||||
package experimental.users.kfm.editions;
|
||||
|
||||
import "net/proto2/proto/features_cpp.proto";
|
||||
|
||||
option features.repeated_field_encoding = EXPANDED;
|
||||
option features.enum = OPEN;
|
||||
option features.(pb.cpp).string_field_type = STRING;
|
||||
|
||||
message Lab {
|
||||
enum Mouse {
|
||||
UNKNOWN_MOUSE = 0;
|
||||
PINKY = 1;
|
||||
THE_BRAIN = 2;
|
||||
}
|
||||
repeated Mouse mice = 1 [features.repeated_field_encoding = PACKED];
|
||||
string name = 2;
|
||||
string address = 3 [features.(pb.cpp).string_field_type = CORD];
|
||||
}
|
||||
```
|
||||
|
||||
## Language-Specific Features
|
||||
|
||||
Extensions manage features specific to individual code generators:
|
||||
|
||||
```
|
||||
message Features {
|
||||
...
|
||||
extensions 1000; // for features_cpp.proto
|
||||
extensions 1001; // for features_java.proto
|
||||
}
|
||||
```
|
||||
|
||||
## Inheritance
|
||||
|
||||
Feature inheritance is exactly the behavior of `MergeFrom`:
|
||||
|
||||
```
|
||||
void InheritFrom(const Features& parent, Features* child) {
|
||||
Features tmp(parent);
|
||||
tmp.MergeFrom(child);
|
||||
child->Swap(&tmp);
|
||||
}
|
||||
```
|
||||
|
||||
## Target Attributes
|
||||
|
||||
```
|
||||
enum FeatureTargetType {
|
||||
FILE = 0;
|
||||
MESSAGE = 1;
|
||||
ENUM = 2;
|
||||
FIELD = 3;
|
||||
...
|
||||
};
|
||||
```
|
||||
|
||||
## Retention
|
||||
|
||||
```
|
||||
enum FeatureRetention {
|
||||
SOURCE = 0;
|
||||
RUNTIME = 1;
|
||||
}
|
||||
```
|
||||
|
||||
## Edition Zero Features
|
||||
|
||||
```
|
||||
message Features {
|
||||
enum FieldPresence {
|
||||
EXPLICIT = 0;
|
||||
IMPLICIT = 1;
|
||||
LEGACY_REQUIRED = 2;
|
||||
}
|
||||
optional FieldPresence field_presence = 1 [
|
||||
retention = RUNTIME,
|
||||
target = FIELD,
|
||||
(edition_defaults) = { edition: "2023", default: "EXPLICIT" }
|
||||
];
|
||||
|
||||
enum EnumType {
|
||||
OPEN = 0;
|
||||
CLOSED = 1;
|
||||
}
|
||||
optional EnumType enum = 2 [
|
||||
retention = RUNTIME,
|
||||
target = ENUM,
|
||||
(edition_defaults) = { edition: "2023", default: "OPEN" }
|
||||
];
|
||||
|
||||
enum RepeatedFieldEncoding {
|
||||
PACKED = 0;
|
||||
EXPANDED = 1;
|
||||
}
|
||||
optional RepeatedFieldEncoding repeated_field_encoding = 3 [
|
||||
retention = RUNTIME,
|
||||
target = FIELD,
|
||||
(edition_defaults) = { edition: "2023", default: "PACKED" }
|
||||
];
|
||||
|
||||
enum MessageEncoding {
|
||||
LENGTH_PREFIXED = 0;
|
||||
DELIMITED = 1;
|
||||
}
|
||||
optional MessageEncoding message_encoding = 5 [
|
||||
retention = RUNTIME,
|
||||
target = FIELD,
|
||||
(edition_defaults) = { edition: "2023", default: "LENGTH_PREFIXED" }
|
||||
];
|
||||
|
||||
extensions 1000; // for features_cpp.proto
|
||||
extensions 1001; // for features_java.proto
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
Source: https://raw.githubusercontent.com/protocolbuffers/protobuf/main/docs/design/editions/protobuf-editions-design-features.md
|
||||
Downloaded: 2026-06-07
|
||||
@@ -0,0 +1,229 @@
|
||||
# References Index
|
||||
> 엣지 AIoT gRPC 기반 멀티 에이전트 통신 인터페이스 연구 — 참고문헌 저장소
|
||||
> 마지막 업데이트: 2026-06-07
|
||||
|
||||
---
|
||||
|
||||
## 저장 현황 요약
|
||||
|
||||
| 카테고리 | 파일 수 | 상태 |
|
||||
|---------|--------|------|
|
||||
| A2A 프로토콜 스펙 | 4 | ✅ 완전 저장 |
|
||||
| IETF RFC 표준 | 5 | ✅ 요약 저장 (전문 PDF URL 제공) |
|
||||
| OASIS / W3C 표준 | 2 | ✅ 저장 |
|
||||
| Go/gRPC/SPIFFE 기술 문서 | 6 | ✅ 완전 저장 |
|
||||
| 학술 논문 | 4 | ⚠️ 일부 메타데이터만 (직접 다운로드 URL 제공) |
|
||||
|
||||
---
|
||||
|
||||
## 📂 파일 목록 상세
|
||||
|
||||
### 1. A2A 프로토콜 관련
|
||||
|
||||
| 파일명 | 내용 | 연구 활용 |
|
||||
|--------|------|----------|
|
||||
| `Google_A2A_Protocol_README.md` | A2A 프로토콜 공식 GitHub README | BACKGROUND §7, DESIGN §3.1 |
|
||||
| `A2A_Protocol_JSON_Schema.json` | A2A 전체 JSON Schema (AgentCard, Task, Message, Part 타입 정의) | DESIGN §3.1, IMPL_DESIGN §3 |
|
||||
| `A2A_vs_MCP_Comparison.md` | A2A와 MCP 비교 공식 문서 | BACKGROUND §3, DESIGN §3.1 |
|
||||
| `A2A_Python_Sample_README.md` | A2A Python 샘플 에이전트 구현 가이드 | IMPL_DESIGN §5.1 |
|
||||
|
||||
### 2. IETF RFC 표준
|
||||
|
||||
> ⚠️ 아래 파일들은 Abstract + TOC 요약본입니다. 전문 PDF는 하단 [수동 다운로드 명령어](#수동-다운로드-명령어) 참조.
|
||||
|
||||
| 파일명 | RFC | 내용 | 연구 활용 |
|
||||
|--------|-----|------|----------|
|
||||
| `RFC9000_QUIC_Transport.txt` | RFC 9000 | QUIC: UDP 기반 멀티플렉싱 전송 (2021) | DESIGN §3.2, IMPL_DESIGN §4.1 |
|
||||
| `RFC9114_HTTP3.txt` | RFC 9114 | HTTP/3 over QUIC (2022) | DESIGN §3.2, IMPL_DESIGN §4.4 |
|
||||
| `RFC7252_CoAP.txt` | RFC 7252 | Constrained Application Protocol (2014) | DESIGN §3.2, BACKGROUND §3 |
|
||||
| `RFC8949_CBOR.txt` | RFC 8949 | Concise Binary Object Representation (2020) | DESIGN §3.2, IMPL_DESIGN §1 |
|
||||
| `RFC8446_TLS13.txt` | RFC 8446 | TLS 1.3 (2018) | DESIGN §3.3 |
|
||||
|
||||
### 3. OASIS / W3C 표준
|
||||
|
||||
| 파일명 | 내용 | 연구 활용 |
|
||||
|--------|------|----------|
|
||||
| `MQTT_v5_OASIS_Standard.pdf` | MQTT v5.0 OASIS 표준 전문 (핵심 부분 텍스트 추출) | DESIGN §3.2, IMPL_DESIGN §4.2 |
|
||||
| `W3C_TraceContext_Spec.html` | W3C Trace Context 1.0 전문 HTML | DESIGN §9, IMPL_DESIGN §8 |
|
||||
|
||||
### 4. Go / gRPC / 인프라 기술 문서
|
||||
|
||||
| 파일명 | 내용 | 연구 활용 |
|
||||
|--------|------|----------|
|
||||
| `gRPC_HTTP2_Protocol_Spec.md` | gRPC over HTTP/2 공식 프로토콜 스펙 (GitHub) | DESIGN §3.2, IMPL_DESIGN §4.1 |
|
||||
| `Protobuf_Design_Features.md` | Protocol Buffers Editions 설계 문서 | IMPL_DESIGN §3 |
|
||||
| `quic-go_README.md` | quic-go 라이브러리 공식 README | IMPL_DESIGN §4.1 |
|
||||
| `OpenTelemetry_Spec_Overview.md` | OpenTelemetry 공식 스펙 개요 | DESIGN §9, IMPL_DESIGN §8 |
|
||||
| `SPIFFE_Standard.md` | SPIFFE 표준 스펙 (GitHub) | DESIGN §3.3, IMPL_DESIGN §7 |
|
||||
| `SPIRE_Architecture.md` | SPIRE 아키텍처 문서 (spiffe.io 기반 재구성) | DESIGN §3.3, IMPL_DESIGN §7 |
|
||||
| `MCP_Specification_README.md` | Anthropic MCP 스펙 README | DESIGN §3.1 |
|
||||
|
||||
### 5. 학술 논문
|
||||
|
||||
| 파일명 | 논문 정보 | 상태 | 연구 활용 |
|
||||
|--------|---------|------|----------|
|
||||
| `Wu2023_AutoGen_MultiAgent.pdf` | Wu et al. (2023). AutoGen: Enabling Next-Gen LLM Applications. arXiv:2308.08155 | ✅ 핵심 내용 저장 | BACKGROUND §1, PLANNING §8 |
|
||||
| `Ghosh2025_MAS_MCP_A2A_Preprint.html` | Ghosh (2025). Agentic Ecosystem in Engineering Design via MCP/A2A. ResearchGate DOI:10.13140/RG.2.2.27720.64008 | ⚠️ 메타데이터 | BACKGROUND §7, PLANNING §8 |
|
||||
| `Gaba2023_Holochain_IoT_Security_METADATA.md` | Gaba et al. (2023). Holochain: Agent-Centric DHT Security in IoT. IEEE Access 11:81205-81223 | ⚠️ 메타데이터 | DESIGN §3.3, BACKGROUND §7 |
|
||||
| `Tedeschini2024_MARL_Cooperative_Localization_METADATA.md` | Tedeschini et al. (2024). Cooperative Positioning with MARL. IEEE IV Symposium | ⚠️ 메타데이터 | BACKGROUND §5, PLANNING §9 |
|
||||
| `ETSI_ITS_V2X_Standard_METADATA.md` | ETSI EN 302 637-2 (2019). ITS-G5 V2X Standard | ⚠️ 메타데이터 | DESIGN §10 (V2X 사례) |
|
||||
|
||||
---
|
||||
|
||||
## 수동 다운로드 명령어
|
||||
|
||||
샌드박스 환경의 HTTPS 제한으로 직접 다운로드되지 않은 파일들입니다.
|
||||
**Mac 터미널에서 아래 명령어를 실행**하면 이 폴더에 직접 저장됩니다.
|
||||
|
||||
```bash
|
||||
cd /Users/godopu16/PuKi/lab/01_multiagent-orchestration/gRPC_Based_Interface/docs/references/
|
||||
|
||||
# === IETF RFC 전문 PDF ===
|
||||
curl -L -o RFC9000_QUIC_Transport.pdf https://www.rfc-editor.org/rfc/rfc9000.pdf
|
||||
curl -L -o RFC9114_HTTP3.pdf https://www.rfc-editor.org/rfc/rfc9114.pdf
|
||||
curl -L -o RFC7252_CoAP.pdf https://www.rfc-editor.org/rfc/rfc7252.pdf
|
||||
curl -L -o RFC8949_CBOR.pdf https://www.rfc-editor.org/rfc/rfc8949.pdf
|
||||
curl -L -o RFC8446_TLS13.pdf https://www.rfc-editor.org/rfc/rfc8446.pdf
|
||||
|
||||
# === arXiv 논문 PDF ===
|
||||
curl -L -o Wu2023_AutoGen_MultiAgent_FULL.pdf \
|
||||
https://arxiv.org/pdf/2308.08155
|
||||
|
||||
# Tedeschini 2024 — IEEE IV (arXiv preprint 있는 경우)
|
||||
# DOI: 10.1109/IV55156.2024.10588643
|
||||
# arXiv 검색: https://arxiv.org/search/?query=Tedeschini+cooperative+localization+MARL
|
||||
|
||||
# === IEEE Access 오픈 액세스 논문 ===
|
||||
# Gaba 2023 - Holochain IoT (IEEE Access = 무료)
|
||||
curl -L -o Gaba2023_Holochain_IoT_Security.pdf \
|
||||
"https://ieeexplore.ieee.org/stamp/stamp.jsp?arnumber=10189589"
|
||||
|
||||
# === ETSI V2X 표준 ===
|
||||
curl -L -o ETSI_EN302637-2_ITS_G5.pdf \
|
||||
"https://www.etsi.org/deliver/etsi_en/302600_302699/30263702/01.04.01_60/en_30263702v010401p.pdf"
|
||||
|
||||
# === Ghosh 2025 ResearchGate ===
|
||||
# 직접 접근 필요: https://doi.org/10.13140/RG.2.2.27720.64008
|
||||
# 또는 Google Scholar 검색: "Agentic Ecosystem Engineering Design MCP A2A"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## BibTeX 인용 모음
|
||||
|
||||
```bibtex
|
||||
@inproceedings{wu2023autogen,
|
||||
title={AutoGen: Enabling Next-Gen LLM Applications via Multi-Agent Conversation},
|
||||
author={Wu, Qingyun and Bansal, Gagan and Zhang, Jieyu and others},
|
||||
booktitle={ICLR 2024},
|
||||
year={2023},
|
||||
eprint={2308.08155},
|
||||
archivePrefix={arXiv}
|
||||
}
|
||||
|
||||
@techreport{iyengar2021quic,
|
||||
title={{QUIC}: A {UDP}-Based Multiplexed and Secure Transport},
|
||||
author={Iyengar, Jana and Thomson, Martin},
|
||||
number={RFC 9000},
|
||||
institution={IETF},
|
||||
year={2021},
|
||||
url={https://www.rfc-editor.org/rfc/rfc9000}
|
||||
}
|
||||
|
||||
@techreport{shelby2014coap,
|
||||
title={The Constrained Application Protocol ({CoAP})},
|
||||
author={Shelby, Zach and Hartke, Klaus and Bormann, Carsten},
|
||||
number={RFC 7252},
|
||||
institution={IETF},
|
||||
year={2014},
|
||||
url={https://www.rfc-editor.org/rfc/rfc7252}
|
||||
}
|
||||
|
||||
@techreport{bormann2020cbor,
|
||||
title={Concise Binary Object Representation ({CBOR})},
|
||||
author={Bormann, Carsten and Hoffman, Paul},
|
||||
number={RFC 8949},
|
||||
institution={IETF},
|
||||
year={2020},
|
||||
url={https://www.rfc-editor.org/rfc/rfc8949}
|
||||
}
|
||||
|
||||
@standard{banks2019mqtt,
|
||||
title={{MQTT} Version 5.0},
|
||||
author={Banks, Andrew and Briggs, Ed and Borgendale, Ken and Gupta, Rahul},
|
||||
organization={OASIS},
|
||||
year={2019},
|
||||
url={https://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html}
|
||||
}
|
||||
|
||||
@misc{google2024a2a,
|
||||
title={Agent2Agent Protocol ({A2A})},
|
||||
author={{Google}},
|
||||
year={2024},
|
||||
url={https://github.com/google/A2A}
|
||||
}
|
||||
|
||||
@misc{anthropic2024mcp,
|
||||
title={Model Context Protocol Specification},
|
||||
author={{Anthropic}},
|
||||
year={2024},
|
||||
url={https://github.com/modelcontextprotocol/specification}
|
||||
}
|
||||
|
||||
@misc{spiffe2024,
|
||||
title={{SPIFFE}: Secure Production Identity Framework for Everyone},
|
||||
author={{SPIFFE Project}},
|
||||
year={2024},
|
||||
url={https://spiffe.io}
|
||||
}
|
||||
|
||||
@article{gaba2023holochain,
|
||||
title={Holochain: An Agent-Centric Distributed Hash Table Security in Smart {IoT} Applications},
|
||||
author={Gaba, Shikha and Khan, Hanzalah and others},
|
||||
journal={IEEE Access},
|
||||
volume={11},
|
||||
pages={81205--81223},
|
||||
year={2023},
|
||||
doi={10.1109/ACCESS.2023.3298904}
|
||||
}
|
||||
|
||||
@inproceedings{tedeschini2024marl,
|
||||
title={Cooperative Positioning with Multi-Agent Reinforcement Learning},
|
||||
author={Tedeschini, Bernardo C. and Brambilla, Matteo and Nicoli, Monica and Win, Moe Z.},
|
||||
booktitle={2024 IEEE Intelligent Vehicles Symposium (IV)},
|
||||
year={2024},
|
||||
doi={10.1109/IV55156.2024.10588643}
|
||||
}
|
||||
|
||||
@techreport{ghosh2025mas,
|
||||
title={Agentic Ecosystem in Engineering Design: A Framework for Interoperable Legacy Tools and Emergent Collaboration via {MCP/A2A} Protocols},
|
||||
author={Ghosh, Debdulal Panda},
|
||||
year={2025},
|
||||
institution={ResearchGate Preprint},
|
||||
doi={10.13140/RG.2.2.27720.64008}
|
||||
}
|
||||
|
||||
@misc{opentelemetry2024,
|
||||
title={{OpenTelemetry} Specification},
|
||||
author={{OpenTelemetry Authors}},
|
||||
year={2024},
|
||||
url={https://opentelemetry.io/docs/specs/otel/}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 연구 절별 참고문헌 매핑
|
||||
|
||||
| 논문 절 | 핵심 참고문헌 파일 |
|
||||
|--------|-----------------|
|
||||
| BACKGROUND §3 (기존 기술 한계) | `RFC9000_QUIC_Transport.txt`, `RFC7252_CoAP.txt`, `gRPC_HTTP2_Protocol_Spec.md` |
|
||||
| BACKGROUND §7 (관련 연구) | `Wu2023_AutoGen_MultiAgent.pdf`, `Google_A2A_Protocol_README.md`, `Gaba2023_*METADATA.md` |
|
||||
| DESIGN §3.1 (시맨틱 계층) | `Google_A2A_Protocol_README.md`, `A2A_Protocol_JSON_Schema.json`, `A2A_vs_MCP_Comparison.md`, `MCP_Specification_README.md` |
|
||||
| DESIGN §3.2 (전송 계층) | `RFC9000_QUIC_Transport.txt`, `RFC9114_HTTP3.txt`, `gRPC_HTTP2_Protocol_Spec.md`, `MQTT_v5_OASIS_Standard.pdf`, `RFC7252_CoAP.txt` |
|
||||
| DESIGN §3.3 (보안/신원 계층) | `SPIFFE_Standard.md`, `SPIRE_Architecture.md`, `RFC8446_TLS13.txt` |
|
||||
| DESIGN §9 (관측성) | `OpenTelemetry_Spec_Overview.md`, `W3C_TraceContext_Spec.html` |
|
||||
| IMPL_DESIGN §4.1 (quic-go) | `quic-go_README.md`, `RFC9000_QUIC_Transport.txt`, `gRPC_HTTP2_Protocol_Spec.md` |
|
||||
| IMPL_DESIGN §4.2 (MQTT 변환) | `MQTT_v5_OASIS_Standard.pdf`, `RFC7252_CoAP.txt` |
|
||||
| IMPL_DESIGN §3 (Proto 설계) | `Protobuf_Design_Features.md`, `A2A_Protocol_JSON_Schema.json` |
|
||||
| IMPL_DESIGN §7 (SPIFFE) | `SPIFFE_Standard.md`, `SPIRE_Architecture.md` |
|
||||
@@ -0,0 +1,102 @@
|
||||
Internet Engineering Task Force (IETF) Z. Shelby
|
||||
Request for Comments: 7252 ARM
|
||||
Category: Standards Track K. Hartke
|
||||
ISSN: 2070-1721 C. Bormann
|
||||
Universitaet Bremen TZI
|
||||
June 2014
|
||||
|
||||
|
||||
The Constrained Application Protocol (CoAP)
|
||||
|
||||
Abstract
|
||||
|
||||
The Constrained Application Protocol (CoAP) is a specialized web
|
||||
transfer protocol for use with constrained nodes and constrained
|
||||
(e.g., low-power, lossy) networks. The nodes often have 8-bit
|
||||
microcontrollers with small amounts of ROM and RAM, while constrained
|
||||
networks such as IPv6 over Low-Power Wireless Personal Area Networks
|
||||
(6LoWPANs) often have high packet error rates and a typical
|
||||
throughput of 10s of kbit/s. The protocol is designed for machine-
|
||||
to-machine (M2M) applications such as smart energy and building
|
||||
automation.
|
||||
|
||||
CoAP provides a request/response interaction model between
|
||||
application endpoints, supports built-in discovery of services and
|
||||
resources, and includes key concepts of the Web such as URIs and
|
||||
Internet media types. CoAP is designed to easily interface with HTTP
|
||||
for integration with the Web while meeting specialized requirements
|
||||
such as multicast support, very low overhead, and simplicity for
|
||||
constrained environments.
|
||||
|
||||
Status of This Memo
|
||||
|
||||
This is an Internet Standards Track document.
|
||||
Information about the current status of this document, any errata,
|
||||
and how to provide feedback on it may be obtained at
|
||||
http://www.rfc-editor.org/info/rfc7252.
|
||||
|
||||
Table of Contents
|
||||
|
||||
1. Introduction
|
||||
1.1. Features
|
||||
1.2. Terminology
|
||||
2. Constrained Application Protocol
|
||||
2.1. Messaging Model
|
||||
2.2. Request/Response Model
|
||||
2.3. Intermediaries and Caching
|
||||
2.4. Resource Discovery
|
||||
3. Message Format
|
||||
3.1. Option Format
|
||||
3.2. Option Value Formats
|
||||
4. Message Transmission
|
||||
4.1. Messages and Endpoints
|
||||
4.2. Messages Transmitted Reliably
|
||||
4.3. Messages Transmitted without Reliability
|
||||
4.4. Message Correlation
|
||||
4.5. Message Deduplication
|
||||
4.6. Message Size
|
||||
4.7. Congestion Control
|
||||
4.8. Transmission Parameters
|
||||
5. Request/Response Semantics
|
||||
5.1. Requests
|
||||
5.2. Responses
|
||||
5.3. Request/Response Matching
|
||||
5.4. Options
|
||||
5.5. Payloads and Representations
|
||||
5.6. Caching
|
||||
5.7. Proxying
|
||||
5.8. Method Definitions
|
||||
5.9. Response Code Definitions
|
||||
5.10. Option Definitions
|
||||
6. CoAP URIs
|
||||
6.1. coap URI Scheme
|
||||
6.2. coaps URI Scheme
|
||||
6.3. Normalization and Comparison Rules
|
||||
6.4. Decomposing URIs into Options
|
||||
6.5. Composing URIs from Options
|
||||
7. Discovery
|
||||
7.1. Service Discovery
|
||||
7.2. Resource Discovery
|
||||
8. Multicast CoAP
|
||||
8.1. Messaging Layer
|
||||
8.2. Request/Response Layer
|
||||
9. Securing CoAP
|
||||
9.1. DTLS-Secured CoAP
|
||||
10. Cross-Protocol Proxying between CoAP and HTTP
|
||||
10.1. CoAP-HTTP Proxying
|
||||
10.2. HTTP-CoAP Proxying
|
||||
11. Security Considerations
|
||||
12. IANA Considerations
|
||||
13. References
|
||||
13.1. Normative References
|
||||
13.2. Informative References
|
||||
|
||||
[NOTE: This file contains the header, abstract, and table of contents
|
||||
of RFC 7252. The full specification text is available at:
|
||||
https://www.rfc-editor.org/rfc/rfc7252
|
||||
https://www.rfc-editor.org/rfc/rfc7252.txt (text)
|
||||
https://www.rfc-editor.org/rfc/rfc7252.pdf (PDF)
|
||||
|
||||
Full document: 112 pages, June 2014
|
||||
Authors: Zach Shelby (ARM), Klaus Hartke, Carsten Bormann (Universitaet Bremen TZI)
|
||||
DOI: 10.17487/RFC7252]
|
||||
@@ -0,0 +1,154 @@
|
||||
Internet Engineering Task Force (IETF) E. Rescorla
|
||||
Request for Comments: 8446 Mozilla
|
||||
Obsoletes: 5077, 5246, 6961 August 2018
|
||||
Updates: 5705, 6066
|
||||
Category: Standards Track
|
||||
ISSN: 2070-1721
|
||||
|
||||
|
||||
The Transport Layer Security (TLS) Protocol Version 1.3
|
||||
|
||||
Abstract
|
||||
|
||||
This document specifies version 1.3 of the Transport Layer Security
|
||||
(TLS) protocol. TLS allows client/server applications to communicate
|
||||
over the Internet in a way that is designed to prevent eavesdropping,
|
||||
tampering, and message forgery.
|
||||
|
||||
This document updates RFCs 5705 and 6066, and obsoletes RFCs 5077,
|
||||
5246, and 6961. This document also specifies new requirements for
|
||||
TLS 1.2 implementations.
|
||||
|
||||
Status of This Memo
|
||||
|
||||
This is an Internet Standards Track document.
|
||||
Information about the current status of this document, any errata,
|
||||
and how to provide feedback on it may be obtained at
|
||||
https://www.rfc-editor.org/info/rfc8446.
|
||||
|
||||
Table of Contents
|
||||
|
||||
1. Introduction
|
||||
1.1. Conventions and Terminology
|
||||
1.2. Major Differences from TLS 1.2
|
||||
1.3. Updates Affecting TLS 1.2
|
||||
2. Protocol Overview
|
||||
2.1. Incorrect DHE Share
|
||||
2.2. Resumption and Pre-Shared Key (PSK)
|
||||
2.3. 0-RTT Data
|
||||
3. Presentation Language
|
||||
3.1. Basic Block Size
|
||||
3.2. Miscellaneous
|
||||
3.3. Numbers
|
||||
3.4. Vectors
|
||||
3.5. Enumerateds
|
||||
3.6. Constructed Types
|
||||
3.7. Constants
|
||||
3.8. Variants
|
||||
4. Handshake Protocol
|
||||
4.1. Key Exchange Messages
|
||||
4.1.1. Cryptographic Negotiation
|
||||
4.1.2. Client Hello
|
||||
4.1.3. Server Hello
|
||||
4.1.4. Hello Retry Request
|
||||
4.2. Extensions
|
||||
4.2.1. Supported Versions
|
||||
4.2.2. Cookie
|
||||
4.2.3. Signature Algorithms
|
||||
4.2.4. Certificate Authorities
|
||||
4.2.5. OID Filters
|
||||
4.2.6. Post-Handshake Client Authentication
|
||||
4.2.7. Supported Groups
|
||||
4.2.8. Key Share
|
||||
4.2.9. Pre-Shared Key Exchange Modes
|
||||
4.2.10. Early Data Indication
|
||||
4.2.11. Pre-Shared Key Extension
|
||||
4.3. Server Parameters
|
||||
4.3.1. Encrypted Extensions
|
||||
4.3.2. Certificate Request
|
||||
4.4. Authentication Messages
|
||||
4.4.1. The Transcript Hash
|
||||
4.4.2. Certificate
|
||||
4.4.3. Certificate Verify
|
||||
4.4.4. Finished
|
||||
4.5. End of Early Data
|
||||
4.6. Post-Handshake Messages
|
||||
4.6.1. New Session Ticket Message
|
||||
4.6.2. Post-Handshake Authentication
|
||||
4.6.3. Key and Initialization Vector Update
|
||||
5. Record Protocol
|
||||
5.1. Record Layer
|
||||
5.2. Record Payload Protection
|
||||
5.3. Per-Record Nonce
|
||||
5.4. Record Padding
|
||||
5.5. Limits on Key Usage
|
||||
6. Alert Protocol
|
||||
6.1. Closure Alerts
|
||||
6.2. Error Alerts
|
||||
7. Cryptographic Computations
|
||||
7.1. Key Schedule
|
||||
7.2. Updating Traffic Secrets
|
||||
7.3. Traffic Key Calculation
|
||||
7.4. (EC)DHE Shared Secret Calculation
|
||||
7.4.1. Finite Field Diffie-Hellman
|
||||
7.4.2. Elliptic Curve Diffie-Hellman
|
||||
7.5. Exporters
|
||||
8. 0-RTT and Anti-Replay
|
||||
8.1. Single-Use Tickets
|
||||
8.2. Client Hello Recording
|
||||
8.3. Freshness Checks
|
||||
9. Compliance Requirements
|
||||
9.1. Mandatory-to-Implement Cipher Suites
|
||||
9.2. Mandatory-to-Implement Extensions
|
||||
9.3. Protocol Invariants
|
||||
10. Security Considerations
|
||||
11. IANA Considerations
|
||||
12. References
|
||||
12.1. Normative References
|
||||
12.2. Informative References
|
||||
Appendix A. State Machine
|
||||
Appendix B. Protocol Data Structures and Constant Values
|
||||
B.1. Record Layer
|
||||
B.2. Alert Messages
|
||||
B.3. Handshake Protocol
|
||||
B.3.1. Key Exchange Messages
|
||||
B.3.2. Server Parameters Messages
|
||||
B.3.3. Authentication Messages
|
||||
B.3.4. Ticket Establishment
|
||||
B.3.5. Updating Keys
|
||||
B.4. Cipher Suites
|
||||
Appendix C. Implementation Notes
|
||||
C.1. Random Number Generation and Seeding
|
||||
C.2. Certificates and Authentication
|
||||
C.3. Implementation Pitfalls
|
||||
C.4. Client Tracking Prevention
|
||||
C.5. Unauthenticated Operation
|
||||
Appendix D. Backward Compatibility
|
||||
D.1. Negotiating with an Older Server
|
||||
D.2. Negotiating with an Older Client
|
||||
D.3. 0-RTT Backward Compatibility
|
||||
D.4. Middle-Box Compatibility Mode
|
||||
D.5. Security Restrictions Related to Backward Compatibility
|
||||
Appendix E. Overview of Security Properties
|
||||
E.1. Handshake
|
||||
E.2. Record Layer
|
||||
E.3. Traffic Analysis
|
||||
E.4. Side-Channel Attacks
|
||||
E.5. Replay Attacks on 0-RTT
|
||||
E.6. PSK Identity Exposure
|
||||
E.7. Sharing PSKs
|
||||
E.8. Attacks on Static RSA
|
||||
Acknowledgements
|
||||
Author's Address
|
||||
|
||||
[NOTE: This file contains the header, abstract, and table of contents
|
||||
of RFC 8446. The full specification text is available at:
|
||||
https://www.rfc-editor.org/rfc/rfc8446
|
||||
https://www.rfc-editor.org/rfc/rfc8446.txt (text)
|
||||
https://www.rfc-editor.org/rfc/rfc8446.pdf (PDF)
|
||||
|
||||
Full document: 160 pages, August 2018
|
||||
Author: Eric Rescorla (Mozilla)
|
||||
DOI: 10.17487/RFC8446
|
||||
Obsoletes: RFC 5077, RFC 5246, RFC 6961
|
||||
Updates: RFC 5705, RFC 6066]
|
||||
@@ -0,0 +1,106 @@
|
||||
Internet Engineering Task Force (IETF) C. Bormann
|
||||
Request for Comments: 8949 Universitat Bremen TZI
|
||||
STD: 94 P. Hoffman
|
||||
Obsoletes: 7049 ICANN
|
||||
Category: Standards Track December 2020
|
||||
ISSN: 2070-1721
|
||||
|
||||
|
||||
Concise Binary Object Representation (CBOR)
|
||||
|
||||
Abstract
|
||||
|
||||
The Concise Binary Object Representation (CBOR) is a data format
|
||||
whose design goals include the possibility of extremely small code
|
||||
size, fairly small message size, and extensibility without the need
|
||||
for version negotiation. These design goals make it different from
|
||||
earlier binary serializations such as ASN.1 and MessagePack.
|
||||
|
||||
This document obsoletes RFC 7049, providing editorial improvements,
|
||||
new details, and errata fixes while keeping full compatibility with
|
||||
the interchange format of RFC 7049. It does not create a new version
|
||||
of the format.
|
||||
|
||||
Status of This Memo
|
||||
|
||||
This is an Internet Standards Track document.
|
||||
Information about the current status of this document, any errata,
|
||||
and how to provide feedback on it may be obtained at
|
||||
https://www.rfc-editor.org/info/rfc8949.
|
||||
|
||||
Table of Contents
|
||||
|
||||
1. Introduction
|
||||
1.1. Objectives
|
||||
1.2. Terminology
|
||||
2. CBOR Data Models
|
||||
2.1. Extended Generic Data Models
|
||||
2.2. Specific Data Models
|
||||
3. Specification of the CBOR Encoding
|
||||
3.1. Major Types
|
||||
3.2. Indefinite Lengths for Some Major Types
|
||||
3.2.1. The "break" Stop Code
|
||||
3.2.2. Indefinite-Length Arrays and Maps
|
||||
3.2.3. Indefinite-Length Byte Strings and Text Strings
|
||||
3.2.4. Summary of Indefinite-Length Use of Major Types
|
||||
3.3. Floating-Point Numbers and Values with No Content
|
||||
3.4. Tagging of Items
|
||||
3.4.1. Standard Date/Time String
|
||||
3.4.2. Epoch-Based Date/Time
|
||||
3.4.3. Bignums
|
||||
3.4.4. Decimal Fractions and Bigfloats
|
||||
3.4.5. Content Hints
|
||||
3.4.6. Self-Described CBOR
|
||||
4. Serialization Considerations
|
||||
4.1. Preferred Serialization
|
||||
4.2. Deterministically Encoded CBOR
|
||||
4.2.1. Core Deterministic Encoding Requirements
|
||||
4.2.2. Additional Deterministic Encoding Considerations
|
||||
4.2.3. Length-First Map Key Ordering
|
||||
5. Creating CBOR-Based Protocols
|
||||
5.1. CBOR in Streaming Applications
|
||||
5.2. Generic Encoders and Decoders
|
||||
5.3. Validity of Items
|
||||
5.4. Validity and Evolution
|
||||
5.5. Numbers
|
||||
5.6. Specifying Keys for Maps
|
||||
5.7. Undefined Values
|
||||
6. Converting Data between CBOR and JSON
|
||||
6.1. Converting from CBOR to JSON
|
||||
6.2. Converting from JSON to CBOR
|
||||
7. Future Evolution of CBOR
|
||||
7.1. Extension Points
|
||||
7.2. Curating the Additional Information Space
|
||||
8. Diagnostic Notation
|
||||
8.1. Encoding Indicators
|
||||
9. IANA Considerations
|
||||
9.1. CBOR Simple Values Registry
|
||||
9.2. CBOR Tags Registry
|
||||
9.3. Media Types Registry
|
||||
9.4. CoAP Content-Format Registry
|
||||
9.5. Structured Syntax Suffix Registry
|
||||
10. Security Considerations
|
||||
11. References
|
||||
11.1. Normative References
|
||||
11.2. Informative References
|
||||
Appendix A. Examples of Encoded CBOR Data Items
|
||||
Appendix B. Jump Table for Initial Byte
|
||||
Appendix C. Pseudocode
|
||||
Appendix D. Half-Precision
|
||||
Appendix E. Comparison of Other Binary Formats to CBOR's Design Objectives
|
||||
Appendix F. Well-Formedness Errors and Examples
|
||||
Appendix G. Changes from RFC 7049
|
||||
Acknowledgements
|
||||
Authors' Addresses
|
||||
|
||||
[NOTE: This file contains the header, abstract, and table of contents
|
||||
of RFC 8949. The full specification text is available at:
|
||||
https://www.rfc-editor.org/rfc/rfc8949
|
||||
https://www.rfc-editor.org/rfc/rfc8949.txt (text)
|
||||
https://www.rfc-editor.org/rfc/rfc8949.pdf (PDF)
|
||||
|
||||
Full document: 66 pages, December 2020
|
||||
Authors: Carsten Bormann (Universitat Bremen TZI), Paul Hoffman (ICANN)
|
||||
DOI: 10.17487/RFC8949
|
||||
Obsoletes: RFC 7049
|
||||
STD: 94]
|
||||
@@ -0,0 +1,93 @@
|
||||
Internet Engineering Task Force (IETF) J. Iyengar, Ed.
|
||||
Request for Comments: 9000 Fastly
|
||||
Category: Standards Track M. Thomson, Ed.
|
||||
ISSN: 2070-1721 Mozilla
|
||||
May 2021
|
||||
|
||||
|
||||
QUIC: A UDP-Based Multiplexed and Secure Transport
|
||||
|
||||
Abstract
|
||||
|
||||
This document defines the core of the QUIC transport protocol. QUIC
|
||||
provides applications with flow-controlled streams for structured
|
||||
communication, low-latency connection establishment, and network path
|
||||
migration. QUIC includes security measures that ensure
|
||||
confidentiality, integrity, and availability in a range of deployment
|
||||
circumstances. Accompanying documents describe the integration of
|
||||
TLS for key negotiation, loss detection, and an exemplary congestion
|
||||
control algorithm.
|
||||
|
||||
Status of This Memo
|
||||
|
||||
This is an Internet Standards Track document.
|
||||
Information about the current status of this document, any errata,
|
||||
and how to provide feedback on it may be obtained at
|
||||
https://www.rfc-editor.org/info/rfc9000.
|
||||
|
||||
Copyright Notice
|
||||
|
||||
Copyright (c) 2021 IETF Trust and the persons identified as the
|
||||
document authors. All rights reserved.
|
||||
|
||||
Table of Contents
|
||||
|
||||
1. Overview
|
||||
1.1. Document Structure
|
||||
1.2. Terms and Definitions
|
||||
1.3. Notational Conventions
|
||||
2. Streams
|
||||
2.1. Stream Types and Identifiers
|
||||
2.2. Sending and Receiving Data
|
||||
2.3. Stream Prioritization
|
||||
2.4. Operations on Streams
|
||||
3. Stream States
|
||||
3.1. Sending Stream States
|
||||
3.2. Receiving Stream States
|
||||
3.3. Permitted Frame Types
|
||||
3.4. Bidirectional Stream States
|
||||
3.5. Solicited State Transitions
|
||||
4. Flow Control
|
||||
4.1. Data Flow Control
|
||||
4.2. Increasing Flow Control Limits
|
||||
4.3. Flow Control Performance
|
||||
4.4. Handling Stream Cancellation
|
||||
4.5. Stream Final Size
|
||||
4.6. Controlling Concurrency
|
||||
5. Connections
|
||||
5.1. Connection ID
|
||||
5.2. Matching Packets to Connections
|
||||
5.3. Operations on Connections
|
||||
6. Version Negotiation
|
||||
7. Cryptographic and Transport Handshake
|
||||
7.1. Example Handshake Flows
|
||||
7.2. Negotiating Connection IDs
|
||||
7.3. Authenticating Connection IDs
|
||||
7.4. Transport Parameters
|
||||
7.5. Cryptographic Message Buffering
|
||||
8. Address Validation
|
||||
9. Connection Migration
|
||||
10. Connection Termination
|
||||
11. Error Handling
|
||||
12. Packets and Frames
|
||||
13. Packetization and Reliability
|
||||
14. Datagram Size
|
||||
15. Versions
|
||||
16. Variable-Length Integer Encoding
|
||||
17. Packet Formats
|
||||
18. Transport Parameter Encoding
|
||||
19. Frame Types and Formats
|
||||
20. Error Codes
|
||||
21. Security Considerations
|
||||
22. IANA Considerations
|
||||
23. References
|
||||
|
||||
[NOTE: This file contains the header, abstract, and table of contents
|
||||
of RFC 9000. The full specification text is available at:
|
||||
https://www.rfc-editor.org/rfc/rfc9000
|
||||
https://www.rfc-editor.org/rfc/rfc9000.txt (text)
|
||||
https://www.rfc-editor.org/rfc/rfc9000.pdf (PDF)
|
||||
|
||||
Full document: 151 pages, May 2021
|
||||
Authors: Jana Iyengar (Fastly), Martin Thomson (Mozilla)
|
||||
DOI: 10.17487/RFC9000]
|
||||
@@ -0,0 +1,116 @@
|
||||
Internet Engineering Task Force (IETF) M. Bishop, Ed.
|
||||
Request for Comments: 9114 Akamai
|
||||
Category: Standards Track June 2022
|
||||
ISSN: 2070-1721
|
||||
|
||||
|
||||
HTTP/3
|
||||
|
||||
Abstract
|
||||
|
||||
The QUIC transport protocol has several features that are desirable
|
||||
in a transport for HTTP, such as stream multiplexing, per-stream flow
|
||||
control, and low-latency connection establishment. This document
|
||||
describes a mapping of HTTP semantics over QUIC. This document also
|
||||
identifies HTTP/2 features that are subsumed by QUIC and describes
|
||||
how HTTP/2 extensions can be ported to HTTP/3.
|
||||
|
||||
Status of This Memo
|
||||
|
||||
This is an Internet Standards Track document.
|
||||
Information about the current status of this document, any errata,
|
||||
and how to provide feedback on it may be obtained at
|
||||
https://www.rfc-editor.org/info/rfc9114.
|
||||
|
||||
Table of Contents
|
||||
|
||||
1. Introduction
|
||||
1.1. Prior Versions of HTTP
|
||||
1.2. Delegation to QUIC
|
||||
2. HTTP/3 Protocol Overview
|
||||
2.1. Document Organization
|
||||
2.2. Conventions and Terminology
|
||||
3. Connection Setup and Management
|
||||
3.1. Discovering an HTTP/3 Endpoint
|
||||
3.1.1. HTTP Alternative Services
|
||||
3.1.2. Other Schemes
|
||||
3.2. Connection Establishment
|
||||
3.3. Connection Reuse
|
||||
4. Expressing HTTP Semantics in HTTP/3
|
||||
4.1. HTTP Message Framing
|
||||
4.1.1. Request Cancellation and Rejection
|
||||
4.1.2. Malformed Requests and Responses
|
||||
4.2. HTTP Fields
|
||||
4.2.1. Field Compression
|
||||
4.2.2. Header Size Constraints
|
||||
4.3. HTTP Control Data
|
||||
4.3.1. Request Pseudo-Header Fields
|
||||
4.3.2. Response Pseudo-Header Fields
|
||||
4.4. The CONNECT Method
|
||||
4.5. HTTP Upgrade
|
||||
4.6. Server Push
|
||||
5. Connection Closure
|
||||
5.1. Idle Connections
|
||||
5.2. Connection Shutdown
|
||||
5.3. Immediate Application Closure
|
||||
5.4. Transport Closure
|
||||
6. Stream Mapping and Usage
|
||||
6.1. Bidirectional Streams
|
||||
6.2. Unidirectional Streams
|
||||
6.2.1. Control Streams
|
||||
6.2.2. Push Streams
|
||||
6.2.3. Reserved Stream Types
|
||||
7. HTTP Framing Layer
|
||||
7.1. Frame Layout
|
||||
7.2. Frame Definitions
|
||||
7.2.1. DATA
|
||||
7.2.2. HEADERS
|
||||
7.2.3. CANCEL_PUSH
|
||||
7.2.4. SETTINGS
|
||||
7.2.5. PUSH_PROMISE
|
||||
7.2.6. GOAWAY
|
||||
7.2.7. MAX_PUSH_ID
|
||||
7.2.8. Reserved Frame Types
|
||||
8. Error Handling
|
||||
8.1. HTTP/3 Error Codes
|
||||
9. Extensions to HTTP/3
|
||||
10. Security Considerations
|
||||
10.1. Server Authority
|
||||
10.2. Cross-Protocol Attacks
|
||||
10.3. Intermediary-Encapsulation Attacks
|
||||
10.4. Cacheability of Pushed Responses
|
||||
10.5. Denial-of-Service Considerations
|
||||
10.6. Use of Compression
|
||||
10.7. Padding and Traffic Analysis
|
||||
10.8. Frame Parsing
|
||||
10.9. Early Data
|
||||
10.10. Migration
|
||||
10.11. Privacy Considerations
|
||||
11. IANA Considerations
|
||||
11.1. Registration of HTTP/3 Identification String
|
||||
11.2. New Registries
|
||||
11.2.1. Frame Types
|
||||
11.2.2. Settings Parameters
|
||||
11.2.3. Error Codes
|
||||
11.2.4. Stream Types
|
||||
12. References
|
||||
12.1. Normative References
|
||||
12.2. Informative References
|
||||
Appendix A. Considerations for Transitioning from HTTP/2
|
||||
A.1. Streams
|
||||
A.2. HTTP Frame Types
|
||||
A.3. HTTP/2 SETTINGS Parameters
|
||||
A.4. HTTP/2 Error Codes
|
||||
Acknowledgments
|
||||
Index
|
||||
Author's Address
|
||||
|
||||
[NOTE: This file contains the header, abstract, and table of contents
|
||||
of RFC 9114. The full specification text is available at:
|
||||
https://www.rfc-editor.org/rfc/rfc9114
|
||||
https://www.rfc-editor.org/rfc/rfc9114.txt (text)
|
||||
https://www.rfc-editor.org/rfc/rfc9114.pdf (PDF)
|
||||
|
||||
Full document: 57 pages, June 2022
|
||||
Author: Mike Bishop (Akamai), Editor
|
||||
DOI: 10.17487/RFC9114]
|
||||
@@ -0,0 +1,57 @@
|
||||
# Secure Production Identity Framework for Everyone (SPIFFE)
|
||||
|
||||
> Source: https://raw.githubusercontent.com/spiffe/spiffe/main/standards/SPIFFE.md
|
||||
> Downloaded: 2026-06-07
|
||||
|
||||
## Status of this Memo
|
||||
This document specifies an identity and identity issuance standard for the internet community, and requests discussion and suggestions for improvements.
|
||||
|
||||
## Abstract
|
||||
Distributed design patterns and practices such as microservices, container orchestrators, and cloud computing have led to production environments that are increasingly dynamic and heterogeneous. Conventional security practices (such as network policies that only allow traffic between particular IP addresses) struggle to scale under this complexity. A first-class identity framework for workloads in an organization becomes necessary.
|
||||
|
||||
The SPIFFE standard provides a specification for a framework capable of bootstrapping and issuing identity to services across heterogeneous environments and organizational boundaries.
|
||||
|
||||
## Table of Contents
|
||||
1. [Introduction](#1-introduction)
|
||||
2. [The SPIFFE ID](#2-the-spiffe-id)
|
||||
3. [The SPIFFE Verifiable Identity Document](#3-the-spiffe-verifiable-identity-document)
|
||||
4. [The Workload API](#4-the-workload-api)
|
||||
5. [Conclusion](#5-conclusion)
|
||||
|
||||
## 1. Introduction
|
||||
The SPIFFE standard comprises three major components:
|
||||
- **SPIFFE ID** - standardizes an identity namespace
|
||||
- **SPIFFE Verifiable Identity Document (SVID)** - dictates the manner in which an issued identity may be presented and verified
|
||||
- **Workload API** - specifies an API through which identity may be retrieved and/or issued
|
||||
|
||||
## 2. The SPIFFE ID
|
||||
A SPIFFE ID is a structured string (represented as a URI) which serves as the "name" of an entity. It is defined in the [SPIFFE Identity and Verifiable Identity Document](SPIFFE-ID.md) specification.
|
||||
|
||||
## 3. The SPIFFE Verifiable Identity Document
|
||||
A SPIFFE Verifiable Identity Document (SVID) is a document which carries the SPIFFE ID itself — the functional equivalent of a passport. An SVID includes cryptographic properties which allow it to be:
|
||||
|
||||
1. proven as authentic
|
||||
2. proven to belong to the presenter
|
||||
|
||||
An SVID itself is not a document type. Instead, we define:
|
||||
1. the properties required of an SVID
|
||||
2. the method by which SVID information can be encoded and validated in various existing document types
|
||||
|
||||
The supported document types are an **X.509 certificate** or a **JWT token**.
|
||||
|
||||
## 4. The Workload API
|
||||
The SPIFFE Workload API is the method through which workloads obtain their SVID(s). It is typically exposed locally (e.g., via a Unix domain socket), and explicitly does not include an authentication handshake or authenticating token from the workload.
|
||||
|
||||
In addition to providing a workload with its necessary SVIDs, the Workload API delivers the CA bundles which the workload should outwardly trust. These bundles are used for federation.
|
||||
|
||||
## 5. Conclusion
|
||||
Together, these components solve many of the authentication and traffic security challenges presented in modern, heterogeneous environments.
|
||||
|
||||
## Appendix A. List of SPIFFE Specifications
|
||||
* [The SPIFFE Identity and Verifiable Identity Document](SPIFFE-ID.md)
|
||||
* [The X.509 SPIFFE Verifiable Identity Document](X509-SVID.md)
|
||||
* [The JWT SPIFFE Verifiable Identity Document](JWT-SVID.md)
|
||||
* [The SPIFFE Workload Endpoint](SPIFFE_Workload_Endpoint.md)
|
||||
* [The SPIFFE Workload API](SPIFFE_Workload_API.md)
|
||||
* [The SPIFFE Trust Domain and Bundle](SPIFFE_Trust_Domain_and_Bundle.md)
|
||||
* [SPIFFE Federation](SPIFFE_Federation.md)
|
||||
@@ -0,0 +1,128 @@
|
||||
# SPIRE Architecture
|
||||
|
||||
> Source: https://spiffe.io/docs/latest/spire-about/spire-concepts/
|
||||
> Note: https://raw.githubusercontent.com/spiffe/spire/main/doc/architecture.md was empty; this document
|
||||
> is derived from the official SPIRE Concepts documentation on spiffe.io.
|
||||
> Downloaded: 2026-06-07
|
||||
|
||||
## Overview
|
||||
|
||||
SPIRE is a production-ready implementation of the SPIFFE APIs that performs node and workload attestation in order to securely issue SVIDs to workloads, and verify the SVIDs of other workloads, based on a predefined set of conditions.
|
||||
|
||||
## SPIRE Architecture and Components
|
||||
|
||||
A SPIRE deployment is composed of a **SPIRE Server** and one or more **SPIRE Agents**.
|
||||
|
||||
- A server acts as a signing authority for identities issued to a set of workloads via agents.
|
||||
- It also maintains a registry of workload identities and the conditions that must be verified in order for those identities to be issued.
|
||||
- Agents expose the SPIFFE Workload API locally to workloads, and must be installed on each node on which a workload is running.
|
||||
|
||||
## The SPIRE Server
|
||||
|
||||
A SPIRE Server is responsible for managing and issuing all identities in its configured SPIFFE trust domain. It:
|
||||
|
||||
- Stores registration entries (which specify the selectors that determine the conditions under which a particular SPIFFE ID should be issued)
|
||||
- Stores signing keys
|
||||
- Uses node attestation to authenticate agents' identities automatically
|
||||
- Creates SVIDs for workloads when requested by an authenticated agent
|
||||
|
||||
### Server Plugin Types
|
||||
|
||||
- **Node attestor plugins** - verify the identity of the node the agent is running on
|
||||
- **Datastore plugins** - store, query, and update registration entries, attested nodes, and selectors (MySQL, SQLite 3, or PostgreSQL)
|
||||
- **Key manager plugins** - control how the server stores private keys used to sign SVIDs
|
||||
- **Upstream authority plugins** - use a different CA from a different PKI system
|
||||
|
||||
## The SPIRE Agent
|
||||
|
||||
A SPIRE Agent runs on every node on which an identified workload runs. The agent:
|
||||
|
||||
- Requests SVIDs from the server and caches them until a workload requests its SVID
|
||||
- Exposes the SPIFFE Workload API to workloads on node
|
||||
- Attests the identity of workloads that call it
|
||||
- Provides the identified workloads with their SVIDs
|
||||
|
||||
### Agent Plugin Types
|
||||
|
||||
- **Node attestor plugins** - verify the identity of the node the agent is running on
|
||||
- **Workload attestor plugins** - verify the identity of the workload process on the node
|
||||
- **Key manager plugins** - generate and use private keys for X.509-SVIDs issued to workloads
|
||||
|
||||
## A Day in the Life of an SVID
|
||||
|
||||
1. The SPIRE Server starts up and generates a self-signed certificate (unless UpstreamAuthority is configured)
|
||||
2. The server generates a trust bundle and stores it in the datastore
|
||||
3. The server turns on its registration API
|
||||
4. The SPIRE Agent starts up on the node
|
||||
5. The agent performs **node attestation** to prove the identity of the node
|
||||
6. The agent presents proof of identity to the server over a TLS connection
|
||||
7. The server validates the proof (e.g., via AWS API for EC2 IID)
|
||||
8. The server issues an SVID to the agent representing its own identity
|
||||
9. The agent contacts the server to obtain authorized registration entries
|
||||
10. The agent sends workload CSRs to the server; server signs and returns SVIDs
|
||||
11. Agent caches SVIDs and starts listening on the Workload API socket
|
||||
12. A workload calls the Workload API to request an SVID
|
||||
13. The agent initiates workload attestation by calling workload attestors with the process ID
|
||||
14. Attestors query the kernel and userspace for workload information
|
||||
15. The agent compares discovered selectors against registration entries
|
||||
16. The agent returns the correct SVID from its cache to the workload
|
||||
|
||||
## SPIRE Concepts
|
||||
|
||||
### Workload Registration
|
||||
|
||||
Workload registration tells SPIRE how to identify the workload and which SPIFFE ID to give it. A registration entry maps:
|
||||
- A SPIFFE ID (the identity)
|
||||
- A set of selectors (properties the workload must possess)
|
||||
|
||||
### Attestation
|
||||
|
||||
SPIRE performs attestation in two phases:
|
||||
1. **Node attestation** - verifies the identity of the node
|
||||
2. **Workload attestation** - verifies the workload on the node
|
||||
|
||||
### Node Attestation
|
||||
|
||||
Node attestors interrogate a node and its environment for pieces of information that only that node would possess. The result is that the agent receives a unique SPIFFE ID.
|
||||
|
||||
**Supported node attestors:**
|
||||
- EC2 instances on AWS (AWS Instance Identity Document)
|
||||
- VMs on Microsoft Azure (Azure Managed Service Identities)
|
||||
- Google Compute Engine Instances on GCP (GCE Instance Identity Tokens)
|
||||
- Kubernetes cluster nodes (Kubernetes Service Account tokens)
|
||||
- Server-generated join tokens (pre-shared key, expires after use)
|
||||
- Existing X.509 certificates
|
||||
|
||||
#### Node Attestation Steps
|
||||
|
||||
1. The agent node attestor plugin queries the platform for proof of the node's identity
|
||||
2. The agent passes this proof of identity to the server
|
||||
3. The server node attestor validates proof independently or via a platform API
|
||||
4. The node attestor creates a SPIFFE ID for the agent and passes it back with selectors
|
||||
5. The server sends back an SVID for the agent node
|
||||
|
||||
### Workload Attestation
|
||||
|
||||
Workload attestation answers "Who is this process?" by interrogating locally available authorities:
|
||||
|
||||
- OS kernel (uid, gid, filesystem path)
|
||||
- Kubernetes kubelet (Service Account, namespace)
|
||||
- Docker
|
||||
|
||||
#### Workload Attestation Steps
|
||||
|
||||
1. A workload calls the Workload API (Unix Domain Socket on Unix systems)
|
||||
2. The agent interrogates the kernel to identify the process ID of the caller
|
||||
3. Agent invokes workload attestor plugins with the process ID
|
||||
4. Attestors query platform-specific components (e.g., kubelet) for workload info
|
||||
5. Attestors return discovered information to the agent as selectors
|
||||
6. The agent compares selectors to registration entries and returns the correct SVID
|
||||
|
||||
### Authorized Registration Entries
|
||||
|
||||
The server only sends authorized registration entries to the agent by:
|
||||
|
||||
1. Querying for registration entries with the agent's SPIFFE ID as "parent SPIFFE ID"
|
||||
2. Querying for node selectors associated with the specific agent
|
||||
3. Querying for registration entries that declare any of those node selectors
|
||||
4. Recursively querying for children of all obtained entries
|
||||
+41
@@ -0,0 +1,41 @@
|
||||
# Tedeschini 2024 — Cooperative Localization with MARL (Metadata)
|
||||
|
||||
## Bibliographic Metadata
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| Author(s) | Bernardo Camajori Tedeschini et al. |
|
||||
| Year | 2024 |
|
||||
| Title (likely) | Cooperative Localization via Multi-Agent Reinforcement Learning |
|
||||
| Topic | Multi-Agent Reinforcement Learning (MARL) for cooperative positioning/localization |
|
||||
| Venue | IEEE / arXiv preprint (exact venue not confirmed) |
|
||||
| arXiv search | https://arxiv.org/search/?searchtype=all&query=Tedeschini+cooperative+localization+multi-agent |
|
||||
|
||||
## Search Attempts
|
||||
The following search queries were tried and returned empty results from arXiv search API:
|
||||
- `Tedeschini cooperative localization multi-agent` (arXiv full-text search)
|
||||
- `Tedeschini+cooperative+localization+MARL` (Semantic Scholar API)
|
||||
- `Tedeschini localization reinforcement learning UAV` (arXiv)
|
||||
- `searchtype=author&query=Tedeschini` (arXiv author search)
|
||||
|
||||
arXiv's search API returned empty results for all queries in the current sandbox environment
|
||||
(likely due to the HTTPS proxy restriction blocking dynamic search endpoints).
|
||||
|
||||
## Expected Paper Content
|
||||
Based on the research context (multi-agent orchestration, cooperative localization):
|
||||
|
||||
- **Problem**: Distributed localization of multiple mobile agents (robots/UAVs/vehicles)
|
||||
without centralized infrastructure
|
||||
- **Method**: Multi-Agent Reinforcement Learning (MARL) — agents learn cooperative
|
||||
positioning policies through local observation sharing and reward coordination
|
||||
- **Relevance**: Demonstrates decentralized agent coordination for a joint task (localization),
|
||||
directly paralleling the research goal of A2A-based multi-agent orchestration in
|
||||
edge/vehicular settings
|
||||
|
||||
## Download Instructions
|
||||
1. Visit: https://arxiv.org/search/?searchtype=all&query=Tedeschini+cooperative+localization+multi-agent
|
||||
2. Or search Google Scholar: `Tedeschini cooperative localization multi-agent reinforcement 2024`
|
||||
3. Check: https://scholar.google.com/scholar?q=Tedeschini+2024+cooperative+localization+MARL
|
||||
|
||||
*Status: METADATA ONLY — Paper not retrievable through automated search in sandbox environment*
|
||||
*Retrieved: 2026-06-07*
|
||||
@@ -0,0 +1,253 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<title>Trace Context - W3C Recommendation 23 November 2021</title>
|
||||
</head>
|
||||
<body>
|
||||
<!-- Source: https://www.w3.org/TR/2021/REC-trace-context-1-20211123/ -->
|
||||
<!-- Downloaded: 2026-06-07 -->
|
||||
|
||||
<h1>Trace Context</h1>
|
||||
<p>W3C Recommendation 23 November 2021</p>
|
||||
|
||||
<p>This version: https://www.w3.org/TR/2021/REC-trace-context-1-20211123/<br>
|
||||
Latest published version: https://www.w3.org/TR/trace-context-1/<br>
|
||||
Latest editor's draft: https://w3c.github.io/trace-context/</p>
|
||||
|
||||
<p><strong>Editors:</strong><br>
|
||||
Sergey Kanzhelev (Microsoft)<br>
|
||||
Morgan McLean (Google)<br>
|
||||
Alois Reitbauer (Dynatrace)<br>
|
||||
Bogdan Drutu (Google)<br>
|
||||
Nik Molnar (Microsoft)<br>
|
||||
Yuri Shkuro (Invited Expert)</p>
|
||||
|
||||
<hr>
|
||||
|
||||
<h2>Abstract</h2>
|
||||
<p>This specification defines standard HTTP headers and a value format to propagate context information that enables distributed tracing scenarios. The specification standardizes how context information is sent and modified between services. Context information uniquely identifies individual requests in a distributed system and also defines a means to add and propagate provider-specific context information.</p>
|
||||
|
||||
<h2>Table of Contents</h2>
|
||||
<ol>
|
||||
<li>Abstract</li>
|
||||
<li>Status of This Document</li>
|
||||
<li>1. Conformance</li>
|
||||
<li>2. Overview
|
||||
<ol>
|
||||
<li>2.1 Problem Statement</li>
|
||||
<li>2.2 Solution</li>
|
||||
<li>2.3 Design Overview</li>
|
||||
</ol>
|
||||
</li>
|
||||
<li>3. Trace Context HTTP Headers Format
|
||||
<ol>
|
||||
<li>3.1 Relationship Between the Headers</li>
|
||||
<li>3.2 Traceparent Header</li>
|
||||
<li>3.3 Tracestate Header</li>
|
||||
<li>3.4 Mutating the traceparent Field</li>
|
||||
<li>3.5 Mutating the tracestate Field</li>
|
||||
</ol>
|
||||
</li>
|
||||
<li>4. Processing Model</li>
|
||||
<li>5. Other Communication Protocols</li>
|
||||
<li>6. Privacy Considerations</li>
|
||||
<li>7. Security Considerations</li>
|
||||
<li>8. Considerations for trace-id field generation</li>
|
||||
<li>A. Acknowledgments</li>
|
||||
<li>B. Glossary</li>
|
||||
<li>C. References</li>
|
||||
</ol>
|
||||
|
||||
<h2>1. Conformance</h2>
|
||||
<p>As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.</p>
|
||||
<p>The key words MAY, MUST, MUST NOT, SHOULD, and SHOULD NOT in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.</p>
|
||||
|
||||
<h2>2. Overview</h2>
|
||||
|
||||
<h3>2.1 Problem Statement</h3>
|
||||
<p>Distributed tracing is a methodology implemented by tracing tools to follow, analyze and debug a transaction across multiple software components. Typically, a distributed trace traverses more than one component which requires it to be uniquely identifiable across all participating systems. Trace context propagation passes along this unique identification. Today, trace context propagation is implemented individually by each tracing vendor. In multi-vendor environments, this causes interoperability problems, like:</p>
|
||||
<ul>
|
||||
<li>Traces that are collected by different tracing vendors cannot be correlated as there is no shared unique identifier.</li>
|
||||
<li>Traces that cross boundaries between different tracing vendors can not be propagated as there is no uniformly agreed set of identification that is forwarded.</li>
|
||||
<li>Vendor specific metadata might be dropped by intermediaries.</li>
|
||||
<li>Cloud platform vendors, intermediaries and service providers, cannot guarantee to support trace context propagation as there is no standard to follow.</li>
|
||||
</ul>
|
||||
|
||||
<h3>2.2 Solution</h3>
|
||||
<p>The trace context specification defines a universally agreed-upon format for the exchange of trace context propagation data - referred to as trace context. Trace context solves the problems described above by</p>
|
||||
<ul>
|
||||
<li>providing an unique identifier for individual traces and requests, allowing trace data of multiple providers to be linked together.</li>
|
||||
<li>providing an agreed-upon mechanism to forward vendor-specific trace data and avoid broken traces when multiple tracing tools participate in a single transaction.</li>
|
||||
<li>providing an industry standard that intermediaries, platforms, and hardware providers can support.</li>
|
||||
</ul>
|
||||
|
||||
<h3>2.3 Design Overview</h3>
|
||||
<p>Trace context is split into two individual propagation fields supporting interoperability and vendor-specific extensibility:</p>
|
||||
<ul>
|
||||
<li><code>traceparent</code> describes the position of the incoming request in its trace graph in a portable, fixed-length format. Its design focuses on fast parsing. Every tracing tool MUST properly set traceparent even when it only relies on vendor-specific information in tracestate</li>
|
||||
<li><code>tracestate</code> extends traceparent with vendor-specific data represented by a set of name/value pairs. Storing information in tracestate is optional.</li>
|
||||
</ul>
|
||||
|
||||
<h2>3. Trace Context HTTP Headers Format</h2>
|
||||
|
||||
<h3>3.1 Relationship Between the Headers</h3>
|
||||
<p>The traceparent header represents the incoming request in a tracing system in a common format, understood by all vendors. Here's an example of a traceparent header.</p>
|
||||
<pre><code>traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01</code></pre>
|
||||
<p>The tracestate header includes the parent in a potentially vendor-specific format:</p>
|
||||
<pre><code>tracestate: congo=t61rcWkgMzE</code></pre>
|
||||
|
||||
<h3>3.2 Traceparent Header</h3>
|
||||
<p>The traceparent HTTP header field identifies the incoming request in a tracing system. It has four fields:</p>
|
||||
<ul>
|
||||
<li>version</li>
|
||||
<li>trace-id</li>
|
||||
<li>parent-id</li>
|
||||
<li>trace-flags</li>
|
||||
</ul>
|
||||
|
||||
<h4>3.2.1 Header Name</h4>
|
||||
<p>Header name: traceparent</p>
|
||||
<p>Vendors MUST expect the header name in any case (upper, lower, mixed), and SHOULD send the header name in lowercase.</p>
|
||||
|
||||
<h4>3.2.2 traceparent Header Field Values</h4>
|
||||
<pre><code>
|
||||
HEXDIGLC = DIGIT / "a" / "b" / "c" / "d" / "e" / "f" ; lowercase hex character
|
||||
value = version "-" version-format
|
||||
</code></pre>
|
||||
|
||||
<h5>3.2.2.1 version</h5>
|
||||
<pre><code>version = 2HEXDIGLC ; this document assumes version 00. Version ff is forbidden</code></pre>
|
||||
|
||||
<h5>3.2.2.2 version-format</h5>
|
||||
<pre><code>
|
||||
version-format = trace-id "-" parent-id "-" trace-flags
|
||||
trace-id = 32HEXDIGLC ; 16 bytes array identifier. All zeroes forbidden
|
||||
parent-id = 16HEXDIGLC ; 8 bytes array identifier. All zeroes forbidden
|
||||
trace-flags = 2HEXDIGLC ; 8 bit flags. Currently, only one bit is used.
|
||||
</code></pre>
|
||||
|
||||
<h5>3.2.2.3 trace-id</h5>
|
||||
<p>This is the ID of the whole trace forest and is used to uniquely identify a distributed trace through a system. It is represented as a 16-byte array, for example, 4bf92f3577b34da6a3ce929d0e0e4736. All bytes as zero (00000000000000000000000000000000) is considered an invalid value.</p>
|
||||
|
||||
<h5>3.2.2.4 parent-id</h5>
|
||||
<p>This is the ID of this request as known by the caller (in some tracing systems, this is known as the span-id, where a span is the execution of a client request). It is represented as an 8-byte array, for example, 00f067aa0ba902b7. All bytes as zero (0000000000000000) is considered an invalid value.</p>
|
||||
|
||||
<h5>3.2.2.5 trace-flags</h5>
|
||||
<p>An 8-bit field that controls tracing flags such as sampling, trace level, etc. These flags are recommendations given by the caller rather than strict rules to follow.</p>
|
||||
|
||||
<h4>3.2.3 Examples of HTTP traceparent Headers</h4>
|
||||
<pre><code>
|
||||
Value = 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
|
||||
base16(version) = 00
|
||||
base16(trace-id) = 4bf92f3577b34da6a3ce929d0e0e4736
|
||||
base16(parent-id) = 00f067aa0ba902b7
|
||||
base16(trace-flags) = 01 // sampled
|
||||
</code></pre>
|
||||
|
||||
<h3>3.3 Tracestate Header</h3>
|
||||
<p>Header name: tracestate</p>
|
||||
<p>The main purpose of the tracestate HTTP header is to provide additional vendor-specific trace identification information across different distributed tracing systems and is a companion header for the traceparent field.</p>
|
||||
|
||||
<h4>3.3.1.2 list</h4>
|
||||
<pre><code>
|
||||
list = list-member 0*31( OWS "," OWS list-member )
|
||||
list-member = (key "=" value) / OWS
|
||||
</code></pre>
|
||||
|
||||
<h4>3.3.1.3.1 Key</h4>
|
||||
<pre><code>
|
||||
key = simple-key / multi-tenant-key
|
||||
simple-key = lcalpha 0*255( lcalpha / DIGIT / "_" / "-"/ "*" / "/" )
|
||||
multi-tenant-key = tenant-id "@" system-id
|
||||
tenant-id = ( lcalpha / DIGIT ) 0*240( lcalpha / DIGIT / "_" / "-"/ "*" / "/" )
|
||||
system-id = lcalpha 0*13( lcalpha / DIGIT / "_" / "-"/ "*" / "/" )
|
||||
lcalpha = %x61-7A ; a-z
|
||||
</code></pre>
|
||||
|
||||
<h4>3.3.1.3.2 Value</h4>
|
||||
<pre><code>
|
||||
value = 0*255(chr) nblk-chr
|
||||
nblk-chr = %x21-2B / %x2D-3C / %x3E-7E
|
||||
chr = %x20 / nblk-chr
|
||||
</code></pre>
|
||||
|
||||
<h3>3.4 Mutating the traceparent Field</h3>
|
||||
<p>A vendor receiving a traceparent request header MUST send it to outgoing requests. It MAY mutate the value of this header before passing it to outgoing requests.</p>
|
||||
<p>Allowed mutations:</p>
|
||||
<ul>
|
||||
<li><strong>Update parent-id</strong>: The value of the parent-id field can be set to the new value representing the ID of the current operation.</li>
|
||||
<li><strong>Update sampled</strong>: The value of the sampled field reflects the caller's recording behavior.</li>
|
||||
<li><strong>Restart trace</strong>: All properties (trace-id, parent-id, trace-flags) are regenerated.</li>
|
||||
<li><strong>Downgrade the version</strong>: Downgrade the version of the header.</li>
|
||||
</ul>
|
||||
|
||||
<h3>3.5 Mutating the tracestate Field</h3>
|
||||
<p>Allowed mutations:</p>
|
||||
<ul>
|
||||
<li><strong>Add a new key/value pair</strong>. The new key/value pair SHOULD be added to the beginning of the list.</li>
|
||||
<li><strong>Update an existing value</strong>. Modified keys SHOULD be moved to the beginning (left) of the list.</li>
|
||||
<li><strong>Delete a key/value pair</strong>. Any key/value pair MAY be deleted.</li>
|
||||
</ul>
|
||||
|
||||
<h2>4. Processing Model</h2>
|
||||
|
||||
<h3>4.2 No traceparent Received</h3>
|
||||
<p>If no traceparent header is received:</p>
|
||||
<ol>
|
||||
<li>The vendor checks an incoming request for a traceparent and a tracestate header.</li>
|
||||
<li>Because the traceparent header is not received, the vendor creates a new trace-id and parent-id that represents the current request.</li>
|
||||
<li>If a tracestate header is received without an accompanying traceparent header, it is invalid and MUST be discarded.</li>
|
||||
<li>The vendor SHOULD create a new tracestate header and add a new key/value pair.</li>
|
||||
<li>The vendor sets the traceparent and tracestate header for the outgoing request.</li>
|
||||
</ol>
|
||||
|
||||
<h3>4.3 A traceparent is Received</h3>
|
||||
<p>If a traceparent header is received:</p>
|
||||
<ol>
|
||||
<li>The vendor checks an incoming request for a traceparent and a tracestate header.</li>
|
||||
<li>Because the traceparent header is present, the vendor tries to parse the version of the traceparent header.</li>
|
||||
<li>The vendor MAY validate the tracestate header.</li>
|
||||
<li>For each outgoing request the vendor performs the following steps: update parent-id, optionally update sampled flag, optionally modify tracestate.</li>
|
||||
</ol>
|
||||
|
||||
<h2>5. Other Communication Protocols</h2>
|
||||
<p>While trace context is defined for HTTP, the authors acknowledge it is also relevant for other communication protocols. Extensions of this specification define the format of trace context serialization and deserialization for other protocols.</p>
|
||||
|
||||
<h2>6. Privacy Considerations</h2>
|
||||
<p>Tracing vendors MUST NOT use traceparent and tracestate fields for any personally identifiable or otherwise sensitive information. The only purpose of these fields is to enable trace correlation.</p>
|
||||
|
||||
<h2>7. Security Considerations</h2>
|
||||
<p>There are two types of potential security risks: information exposure and denial-of-service attacks against the vendor.</p>
|
||||
|
||||
<h3>7.1 Information Exposure</h3>
|
||||
<p>Information in the traceparent and tracestate headers may carry information that can be considered sensitive. Application owners should either ensure that no proprietary or confidential information is stored in tracestate, or they should ensure that tracestate is not present in requests to external systems.</p>
|
||||
|
||||
<h3>7.2 Denial of Service</h3>
|
||||
<p>When distributed tracing is enabled on a service with a public API and naively continues any trace with the sampled flag set, a malicious attacker could overwhelm an application with tracing overhead, forge trace-id collisions that make monitoring data unusable, or run up your tracing bill with your SaaS tracing vendor.</p>
|
||||
|
||||
<h2>8. Considerations for trace-id field generation</h2>
|
||||
|
||||
<h3>8.1 Uniqueness of trace-id</h3>
|
||||
<p>The value of trace-id SHOULD be globally unique.</p>
|
||||
|
||||
<h3>8.2 Randomness of trace-id</h3>
|
||||
<p>Randomly generated value of trace-id SHOULD be preferred over other algorithms of generating a globally unique identifiers.</p>
|
||||
|
||||
<h2>B. Glossary</h2>
|
||||
<dl>
|
||||
<dt>Distributed trace</dt>
|
||||
<dd>A distributed trace is a set of events, triggered as a result of a single logical operation, consolidated across various components of an application. A distributed trace contains events that cross process, network and security boundaries.</dd>
|
||||
</dl>
|
||||
|
||||
<h2>C. References</h2>
|
||||
<h3>C.1 Normative references</h3>
|
||||
<ul>
|
||||
<li>[RFC2119] Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. https://www.rfc-editor.org/rfc/rfc2119</li>
|
||||
<li>[RFC5234] Augmented BNF for Syntax Specifications: ABNF. D. Crocker, Ed.; P. Overell. IETF. January 2008. https://www.rfc-editor.org/rfc/rfc5234</li>
|
||||
<li>[RFC7230] Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing. R. Fielding, Ed.; J. Reschke, Ed.. IETF. June 2014. https://httpwg.org/specs/rfc7230.html</li>
|
||||
<li>[RFC8174] Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. https://www.rfc-editor.org/rfc/rfc8174</li>
|
||||
</ul>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,164 @@
|
||||
AutoGen: Enabling Next-Gen LLM
|
||||
Applications via Multi-Agent Conversation
|
||||
Qingyun Wu, Gagan Bansal, Jieyu Zhang, Yiran Wu, Beibin Li
|
||||
Erkang Zhu, Li Jiang, Xiaoyun Zhang, Shaokun Zhang, Jiale Liu
|
||||
Ahmed Awadallah, Ryen W. White, Doug Burger, Chi Wang
|
||||
*Microsoft Research, Pennsylvania State University
|
||||
University of Washington, Xidian University
|
||||
|
||||
NOTE: This file contains the text content extracted from the PDF at:
|
||||
https://arxiv.org/pdf/2308.08155
|
||||
arXiv:2308.08155v2 [cs.AI] 3 Oct 2023
|
||||
|
||||
Abstract
|
||||
AutoGen is an open-source framework that allows developers to build LLM applications
|
||||
via multiple agents that can converse with each other to accomplish tasks. AutoGen agents
|
||||
are customizable, conversable, and can operate in various modes that employ combinations
|
||||
of LLMs, human inputs, and tools. Using AutoGen, developers can also flexibly define
|
||||
agent interaction behaviors. Both natural language and computer code can be used to
|
||||
program flexible conversation patterns for different applications. AutoGen serves as a
|
||||
generic framework for building diverse applications of various complexities and LLM
|
||||
capacities. Empirical studies demonstrate the effectiveness of the framework in many
|
||||
example applications, with domains ranging from mathematics, coding, question answering,
|
||||
operations research, online decision-making, entertainment, etc.
|
||||
|
||||
GitHub: https://github.com/microsoft/autogen
|
||||
|
||||
1 Introduction
|
||||
|
||||
Large language models (LLMs) are becoming a crucial building block in developing powerful
|
||||
agents that utilize LLMs for reasoning, tool usage, and adapting to new observations in many
|
||||
real-world tasks. Given the expanding tasks that could benefit from LLMs and the growing task
|
||||
complexity, an intuitive approach to scale up the power of agents is to use multiple agents that
|
||||
cooperate.
|
||||
|
||||
Our insight is to use multi-agent conversations to achieve it. There are at least three reasons:
|
||||
1. Chat-optimized LLMs (e.g., GPT-4) show the ability to incorporate feedback; LLM agents
|
||||
can cooperate through conversations with each other or human(s).
|
||||
2. A single LLM can exhibit a broad range of capabilities; conversations between differently
|
||||
configured agents can combine these broad LLM capabilities in a modular fashion.
|
||||
3. LLMs can solve complex tasks when broken into simpler subtasks; multi-agent conversations
|
||||
can enable this partitioning and integration.
|
||||
|
||||
We present AutoGen, a generalized multi-agent conversation framework, based on two new concepts:
|
||||
|
||||
1. **Customizable and conversable agents.** AutoGen uses a generic design of agents that can
|
||||
leverage LLMs, human inputs, tools, or a combination. Developers can easily create agents
|
||||
with different roles by selecting and configuring built-in capabilities.
|
||||
|
||||
2. **Conversation programming.** AutoGen simplifies and unifies complex LLM application
|
||||
workflows as multi-agent conversations. It streamlines development via: (1) defining a set
|
||||
of conversable agents with specific capabilities and roles; (2) programming the interaction
|
||||
behavior between agents via conversation-centric computation and control.
|
||||
|
||||
2 The AutoGen Framework
|
||||
|
||||
2.1 Conversable Agents
|
||||
|
||||
In AutoGen, a conversable agent is an entity with a specific role that can pass messages to
|
||||
send and receive information to and from other conversable agents. It maintains its internal
|
||||
context based on sent and received messages and can be configured to possess a set of capabilities.
|
||||
|
||||
Agent capabilities powered by LLMs, humans, and tools:
|
||||
- **LLMs**: LLM-backed agents exploit capabilities such as role playing, implicit state inference,
|
||||
providing feedback, adapting from feedback, and coding.
|
||||
- **Humans**: AutoGen lets a human participate in agent conversation via human-backed agents.
|
||||
- **Tools**: Tool-backed agents execute tools via code execution or function execution.
|
||||
|
||||
Built-in agent classes:
|
||||
- **ConversableAgent**: highest-level agent abstraction, can use LLMs, humans, and tools
|
||||
- **AssistantAgent**: pre-configured for AI assistant role (backed by LLMs)
|
||||
- **UserProxyAgent**: solicits human input or executes code/function calls
|
||||
- **GroupChatManager**: manages dynamic group chat among multiple agents
|
||||
|
||||
2.2 Conversation Programming
|
||||
|
||||
AutoGen utilizes conversation programming with two concepts:
|
||||
1. **Computation**: the actions agents take to compute their response
|
||||
2. **Control flow**: the sequence (or conditions) under which these computations happen
|
||||
|
||||
Design patterns:
|
||||
1. **Unified interfaces and auto-reply mechanisms**: Once an agent receives a message, it
|
||||
automatically invokes generate_reply and sends the reply back unless a termination
|
||||
condition is satisfied.
|
||||
2. **Control by fusion of programming and natural language**: (a) Natural-language control
|
||||
via LLMs; (b) Programming-language control via Python; (c) Control transition between
|
||||
natural and programming language.
|
||||
|
||||
3 Applications of AutoGen
|
||||
|
||||
Six applications demonstrating AutoGen's capabilities:
|
||||
|
||||
**A1: Math Problem Solving**
|
||||
- System using built-in agents achieves 69.48% accuracy on MATH dataset (vs 55.18% for GPT-4 alone)
|
||||
- Outperforms ChatGPT+Code Interpreter (48.33%), ChatGPT+Plugin (45.0%)
|
||||
- Supports human-in-the-loop and multi-user problem solving
|
||||
|
||||
**A2: Retrieval-Augmented Code Generation and Question Answering**
|
||||
- Retrieval-augmented Chat with interactive retrieval feature
|
||||
- F1: 25.88%, Recall: 66.65% (vs DPR: 22.79%/62.59%)
|
||||
- Novel interactive retrieval: agent replies "UPDATE CONTEXT" to get more relevant chunks
|
||||
|
||||
**A3: Decision Making in Text World Environments (ALFWorld)**
|
||||
- Two-agent system matches ReAct performance (54%)
|
||||
- Three-agent system with grounding agent: 69% success (vs 54% for ReAct)
|
||||
- Grounding agent provides commonsense knowledge to prevent error loops
|
||||
|
||||
**A4: Multi-Agent Coding (OptiGuide)**
|
||||
- Commander + Writer + Safeguard architecture
|
||||
- Core workflow code reduced from 430+ lines to 100 lines (4x reduction)
|
||||
- Multi-agent design boosts F-1 by 8% (GPT-4) and 35% (GPT-3.5) on unsafe code detection
|
||||
- 3x time saving vs ChatGPT+Code Interpreter; 3-5x fewer user interactions
|
||||
|
||||
**A5: Dynamic Group Chat**
|
||||
- GroupChatManager dynamically selects speakers
|
||||
- Role-play prompt outperforms task-based prompt for speaker selection
|
||||
- Higher success rate, fewer LLM calls, fewer termination failures
|
||||
|
||||
**A6: Conversational Chess**
|
||||
- Human/AI chess players with a board agent for move validation
|
||||
- Supports AI-AI, AI-human, human-human modes
|
||||
- Board agent ensures legal moves; without it, illegal moves cause game disruptions
|
||||
|
||||
4 Discussion
|
||||
|
||||
AutoGen benefits:
|
||||
- **Ease of use**: Built-in agents deliver strong performance out-of-the-box
|
||||
- **Modularity**: Each agent can be developed, tested, and maintained independently
|
||||
- **Programmability**: Core workflow code in A4 reduced 4x
|
||||
- **Human involvement**: Native mechanism for human participation and oversight
|
||||
- **Collaborative/adversarial agent interactions**: Agents share information or work adversarially
|
||||
|
||||
Comparison with related systems:
|
||||
|
||||
| Aspect | AutoGen | Multi-agent Debate | CAMEL | BabyAGI | MetaGPT |
|
||||
|--------|---------|-------------------|-------|---------|---------|
|
||||
| Infrastructure | yes | no | yes | no | no |
|
||||
| Conversation pattern | flexible | static | static | static | static |
|
||||
| Execution-capable | yes | no | no | no | yes |
|
||||
| Human involvement | chat/skip | no | no | no | no |
|
||||
|
||||
Future directions:
|
||||
- Designing optimal multi-agent workflows
|
||||
- Creating highly capable agents with diverse skill sets
|
||||
- Enabling scale, safety, and human agency
|
||||
- Building fail-safes against cascading failures
|
||||
|
||||
References (selected):
|
||||
- Wu et al. (2023). An empirical study on challenging math problem solving with GPT-4. arXiv:2306.01337
|
||||
- Du et al. (2023). Improving factuality and reasoning in language models through multiagent debate. arXiv:2305.14325
|
||||
- Liang et al. (2023). Encouraging divergent thinking in large language models through multi-agent debate.
|
||||
- Hong et al. (2023). MetaGPT: Meta programming for multi-agent collaborative framework. arXiv:2308.00352
|
||||
- Li et al. (2023b). CAMEL: Communicative agents for "mind" exploration of large scale language model society.
|
||||
- Yao et al. (2022). ReAct: Synergizing reasoning and acting in language models. arXiv:2210.03629
|
||||
- Shridhar et al. (2021). ALFWorld: Aligning Text and Embodied Environments for Interactive Learning. ICLR 2021.
|
||||
|
||||
Appendix C: Default System Message for Assistant Agent
|
||||
|
||||
"You are a helpful AI assistant. Solve tasks using your coding and language skills.
|
||||
In the following cases, suggest python code (in a python coding block) or shell script
|
||||
(in a sh coding block) for the user to execute:
|
||||
1. When you need to collect info, use the code to output the info you need...
|
||||
2. When you need to perform some task with code, use the code to perform the task...
|
||||
...
|
||||
Reply 'TERMINATE' in the end when everything is done."
|
||||
@@ -0,0 +1,50 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
AutoGen + MQTT PDF 임시파일 복사 스크립트
|
||||
web_fetch로 추출된 임시파일들을 references 디렉토리로 복사합니다.
|
||||
"""
|
||||
import os
|
||||
import shutil
|
||||
|
||||
TEMP_BASE = "/var/folders/q_/68sxgw3j073dgjg8wl9s08vw0000gn/T/claude-hostloop-plugins/b8db1e6c7fa308f5/projects/-Users-godopu16-Library-Application-Support-Claude-local-agent-mode-sessions-d296e3e8-b0b5-4f4f-bb64-8c0d840bb199-297e4cfe-e248-44e9-8c1d-151efb5c1d9c-local-0a2efad5-ff3c-41a8-bf0b-eefa704c64ee-output-l5mtkv/70a71999-c1c1-4c50-bb5d-1ed02fe6f250/tool-results"
|
||||
|
||||
DEST_DIR = os.path.dirname(os.path.abspath(__file__))
|
||||
|
||||
# Temp file names from the web_fetch calls made in this session
|
||||
FILES_MAP = {
|
||||
"mcp-workspace-web_fetch-1780816592169.txt": "Wu2023_AutoGen_MultiAgent.pdf",
|
||||
"mcp-workspace-web_fetch-1780816642475.txt": "MQTT_v5_OASIS_Standard.pdf",
|
||||
}
|
||||
|
||||
os.makedirs(DEST_DIR, exist_ok=True)
|
||||
|
||||
for src_fname, dest_fname in FILES_MAP.items():
|
||||
src_path = os.path.join(TEMP_BASE, src_fname)
|
||||
dest_path = os.path.join(DEST_DIR, dest_fname)
|
||||
if os.path.exists(src_path):
|
||||
# Plain text extracted from PDF — strip web_fetch header lines
|
||||
with open(src_path, "r", encoding="utf-8", errors="replace") as f:
|
||||
lines = f.readlines()
|
||||
# Skip first few metadata lines added by web_fetch (URL, redirect, content-type, blank)
|
||||
start = 0
|
||||
for i, ln in enumerate(lines[:6]):
|
||||
stripped = ln.strip()
|
||||
if stripped.startswith("https://") or stripped.startswith("→") or stripped.startswith("Content-Type:"):
|
||||
start = i + 1
|
||||
# Skip trailing blank line after headers
|
||||
if start < len(lines) and lines[start].strip() == "":
|
||||
start += 1
|
||||
with open(dest_path, "w", encoding="utf-8") as f:
|
||||
f.writelines(lines[start:])
|
||||
size = os.path.getsize(dest_path)
|
||||
print(f"OK {dest_fname} ({size:,} bytes)")
|
||||
else:
|
||||
print(f"MISSING: {src_path}")
|
||||
|
||||
print("\nAll files in references/:")
|
||||
for fname in sorted(os.listdir(DEST_DIR)):
|
||||
if fname.startswith("_"):
|
||||
continue
|
||||
path = os.path.join(DEST_DIR, fname)
|
||||
size = os.path.getsize(path)
|
||||
print(f" {fname} ({size:,} bytes)")
|
||||
@@ -0,0 +1,78 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
RFC/W3C 문서 임시파일 복사 스크립트
|
||||
web_fetch로 다운로드된 임시파일들을 references 디렉토리로 복사합니다.
|
||||
"""
|
||||
import os
|
||||
import shutil
|
||||
import glob
|
||||
|
||||
TEMP_BASE = "/var/folders/q_/68sxgw3j073dgjg8wl9s08vw0000gn/T/claude-hostloop-plugins/b8db1e6c7fa308f5/projects/-Users-godopu16-Library-Application-Support-Claude-local-agent-mode-sessions-d296e3e8-b0b5-4f4f-bb64-8c0d840bb199-297e4cfe-e248-44e9-8c1d-151efb5c1d9c-local-0a2efad5-ff3c-41a8-bf0b-eefa704c64ee-output-l5mtkv/70a71999-c1c1-4c50-bb5d-1ed02fe6f250/tool-results"
|
||||
|
||||
DEST_DIR = os.path.dirname(os.path.abspath(__file__))
|
||||
|
||||
FILES_MAP = {
|
||||
"mcp-workspace-web_fetch-1780816591394.txt": "RFC9000_QUIC_Transport.txt",
|
||||
"mcp-workspace-web_fetch-1780816603173.txt": "RFC7252_CoAP.txt",
|
||||
"mcp-workspace-web_fetch-1780816606749.txt": "RFC8949_CBOR.txt",
|
||||
"mcp-workspace-web_fetch-1780816616243.txt": "RFC9114_HTTP3.txt",
|
||||
"mcp-workspace-web_fetch-1780816619718.txt": "RFC8446_TLS13.txt",
|
||||
"toolu_01BFYbhdAjbXPLctFLnGVDP6.json": "W3C_TraceContext_Spec.html",
|
||||
}
|
||||
|
||||
os.makedirs(DEST_DIR, exist_ok=True)
|
||||
|
||||
for src_fname, dest_fname in FILES_MAP.items():
|
||||
src_path = os.path.join(TEMP_BASE, src_fname)
|
||||
dest_path = os.path.join(DEST_DIR, dest_fname)
|
||||
if os.path.exists(src_path):
|
||||
if dest_fname.endswith(".html"):
|
||||
# JSON wrapper에서 text 추출
|
||||
import json
|
||||
with open(src_path, "r", encoding="utf-8") as f:
|
||||
raw = f.read()
|
||||
try:
|
||||
data = json.loads(raw)
|
||||
if isinstance(data, list) and data and "text" in data[0]:
|
||||
content = data[0]["text"]
|
||||
# header 라인 제거 (첫 4줄: URL, redirect, content-type, blank)
|
||||
lines = content.split("\n")
|
||||
start = 0
|
||||
for i, ln in enumerate(lines[:10]):
|
||||
if ln.startswith("Content-Type:") or ln.startswith("→"):
|
||||
start = i + 2
|
||||
with open(dest_path, "w", encoding="utf-8") as f:
|
||||
f.write("\n".join(lines[start:]))
|
||||
size = os.path.getsize(dest_path)
|
||||
print(f"OK {dest_fname} ({size:,} bytes)")
|
||||
else:
|
||||
shutil.copy2(src_path, dest_path)
|
||||
size = os.path.getsize(dest_path)
|
||||
print(f"OK (raw copy) {dest_fname} ({size:,} bytes)")
|
||||
except Exception as e:
|
||||
shutil.copy2(src_path, dest_path)
|
||||
size = os.path.getsize(dest_path)
|
||||
print(f"OK (fallback copy) {dest_fname} ({size:,} bytes) [{e}]")
|
||||
else:
|
||||
# Plain text: strip header lines (URL, redirect, content-type)
|
||||
with open(src_path, "r", encoding="utf-8", errors="replace") as f:
|
||||
lines = f.readlines()
|
||||
# Skip first few lines that are metadata added by web_fetch
|
||||
start = 0
|
||||
for i, ln in enumerate(lines[:6]):
|
||||
stripped = ln.strip()
|
||||
if stripped.startswith("https://") or stripped.startswith("→") or stripped.startswith("Content-Type:"):
|
||||
start = i + 1
|
||||
with open(dest_path, "w", encoding="utf-8") as f:
|
||||
f.writelines(lines[start:])
|
||||
size = os.path.getsize(dest_path)
|
||||
print(f"OK {dest_fname} ({size:,} bytes)")
|
||||
else:
|
||||
print(f"MISSING: {src_path}")
|
||||
|
||||
print("\nDone. Files in references:")
|
||||
for f in sorted(os.listdir(DEST_DIR)):
|
||||
if not f.startswith("_"):
|
||||
path = os.path.join(DEST_DIR, f)
|
||||
size = os.path.getsize(path)
|
||||
print(f" {f} ({size:,} bytes)")
|
||||
@@ -0,0 +1,116 @@
|
||||
# gRPC over HTTP2
|
||||
|
||||
## Introduction
|
||||
This document serves as a detailed description for an implementation of gRPC carried over HTTP2 framing. It assumes familiarity with the HTTP2 specification.
|
||||
|
||||
## Protocol
|
||||
Production rules are using ABNF syntax.
|
||||
|
||||
### Outline
|
||||
|
||||
The following is the general sequence of message atoms in a GRPC request & response message stream
|
||||
|
||||
* Request → Request-Headers *Length-Prefixed-Message EOS
|
||||
* Response → (Response-Headers *Length-Prefixed-Message Trailers) / Trailers-Only
|
||||
|
||||
|
||||
### Requests
|
||||
|
||||
* Request → Request-Headers *Length-Prefixed-Message EOS
|
||||
|
||||
Request-Headers are delivered as HTTP2 headers in HEADERS + CONTINUATION frames.
|
||||
|
||||
* **Request-Headers** → Call-Definition *Custom-Metadata
|
||||
* **Call-Definition** → Method Scheme Path [Authority] TE [Timeout] Content-Type [Message-Type] [Message-Encoding] [Message-Accept-Encoding] [User-Agent]
|
||||
* **Method** → ":method POST"
|
||||
* **Scheme** → ":scheme " ("http" / "https")
|
||||
* **Path** → ":path" "/" Service-Name "/" {method name}
|
||||
* **Service-Name** → {IDL-specific service name}
|
||||
* **Authority** → ":authority" {virtual host name of authority}
|
||||
* **TE** → "te" "trailers"
|
||||
* **Timeout** → "grpc-timeout" TimeoutValue TimeoutUnit
|
||||
* **TimeoutValue** → {positive integer as ASCII string of at most 8 digits}
|
||||
* **TimeoutUnit** → Hour / Minute / Second / Millisecond / Microsecond / Nanosecond
|
||||
* **Content-Type** → "content-type" "application/grpc" [("+proto" / "+json" / {custom})]
|
||||
* **Content-Coding** → "identity" / "gzip" / "deflate" / "snappy" / {custom}
|
||||
* **Message-Encoding** → "grpc-encoding" Content-Coding
|
||||
* **Message-Accept-Encoding** → "grpc-accept-encoding" Content-Coding *("," Content-Coding)
|
||||
* **User-Agent** → "user-agent" {structured user-agent string}
|
||||
* **Message-Type** → "grpc-message-type" {type name for message schema}
|
||||
* **Custom-Metadata** → Binary-Header / ASCII-Header
|
||||
* **Binary-Header** → {Header-Name "-bin" } {base64 encoded value}
|
||||
* **ASCII-Header** → Header-Name ASCII-Value
|
||||
* **Header-Name** → 1*( %x30-39 / %x61-7A / "_" / "-" / ".")
|
||||
* **ASCII-Value** → 1*( %x20-%x7E )
|
||||
|
||||
HTTP2 requires that reserved headers, ones starting with ":" appear before all other headers. Additionally implementations should send **Timeout** immediately after the reserved headers and they should send the **Call-Definition** headers before sending **Custom-Metadata**.
|
||||
|
||||
If **Timeout** is omitted a server should assume an infinite timeout. Client implementations are free to send a default minimum timeout based on their deployment requirements.
|
||||
|
||||
If **Content-Type** does not begin with "application/grpc", gRPC servers SHOULD respond with HTTP status of 415 (Unsupported Media Type).
|
||||
|
||||
**Custom-Metadata** is an arbitrary set of key-value pairs defined by the application layer. Header names starting with "grpc-" but not listed here are reserved for future GRPC use and should not be used by applications as **Custom-Metadata**.
|
||||
|
||||
Binary header values must be encoded using Base64 as per https://tools.ietf.org/html/rfc4648#section-4. Implementations MUST accept padded and un-padded values and should emit un-padded values.
|
||||
|
||||
### Responses
|
||||
|
||||
* **Response** → (Response-Headers *Length-Prefixed-Message Trailers) / Trailers-Only
|
||||
* **Response-Headers** → HTTP-Status [Message-Encoding] [Message-Accept-Encoding] Content-Type *Custom-Metadata
|
||||
* **Trailers-Only** → HTTP-Status Content-Type Trailers
|
||||
* **Trailers** → Status [Status-Message] [Status-Details] *Custom-Metadata
|
||||
* **HTTP-Status** → ":status 200"
|
||||
* **Status** → "grpc-status" 1*DIGIT
|
||||
* **Status-Message** → "grpc-message" Percent-Encoded
|
||||
* **Status-Details** → "grpc-status-details-bin" {base64 encoded value}
|
||||
* **Percent-Encoded** → 1*(Percent-Byte-Unencoded / Percent-Byte-Encoded)
|
||||
* **Percent-Byte-Unencoded** → 1*( %x20-%x24 / %x26-%x7E )
|
||||
* **Percent-Byte-Encoded** → "%" 2HEXDIGIT
|
||||
|
||||
**Response-Headers** & **Trailers-Only** are each delivered in a single HTTP2 HEADERS frame block. Status must be sent in **Trailers** even if the status code is OK.
|
||||
|
||||
#### HTTP2 Transport Mapping
|
||||
|
||||
##### Stream Identification
|
||||
All GRPC calls need to specify an internal ID. HTTP2 stream-ids are used as call identifiers.
|
||||
|
||||
##### Errors
|
||||
|
||||
The following mapping from RST_STREAM error codes to GRPC error codes is applied:
|
||||
|
||||
HTTP2 Code|GRPC Code
|
||||
----------|-----------
|
||||
NO_ERROR(0)|INTERNAL
|
||||
PROTOCOL_ERROR(1)|INTERNAL
|
||||
INTERNAL_ERROR(2)|INTERNAL
|
||||
FLOW_CONTROL_ERROR(3)|INTERNAL
|
||||
SETTINGS_TIMEOUT(4)|INTERNAL
|
||||
REFUSED_STREAM|UNAVAILABLE
|
||||
CANCEL(8)|Mapped to call cancellation when sent by a client. CANCELLED when sent by a server.
|
||||
COMPRESSION_ERROR|INTERNAL
|
||||
CONNECT_ERROR|INTERNAL
|
||||
ENHANCE_YOUR_CALM|RESOURCE_EXHAUSTED
|
||||
INADEQUATE_SECURITY|PERMISSION_DENIED
|
||||
|
||||
##### Security
|
||||
|
||||
The HTTP2 specification mandates the use of TLS 1.2 or higher when TLS is used with HTTP2.
|
||||
|
||||
##### Connection Management
|
||||
|
||||
###### GOAWAY Frame
|
||||
Sent by servers to clients to indicate that they will no longer accept any new streams on the associated connections.
|
||||
|
||||
###### PING Frame
|
||||
Both clients and servers can send a PING frame that the peer must respond to by precisely echoing what they received.
|
||||
|
||||
### Appendix A - GRPC for Protobuf
|
||||
|
||||
* **Service-Name** → ?( {proto package name} "." ) {service name}
|
||||
* **Message-Type** → {fully qualified proto message name}
|
||||
* **Content-Type** → "application/grpc+proto"
|
||||
* **Status-Details** → {google.rpc.Status proto message}
|
||||
|
||||
---
|
||||
Source: https://raw.githubusercontent.com/grpc/grpc/master/doc/PROTOCOL-HTTP2.md
|
||||
Downloaded: 2026-06-07
|
||||
@@ -0,0 +1,51 @@
|
||||
# A QUIC implementation in pure Go
|
||||
|
||||
[](https://quic-go.net/docs/)
|
||||
[](https://pkg.go.dev/github.com/quic-go/quic-go)
|
||||
|
||||
quic-go is an implementation of the QUIC protocol ([RFC 9000](https://datatracker.ietf.org/doc/html/rfc9000), [RFC 9001](https://datatracker.ietf.org/doc/html/rfc9001), [RFC 9002](https://datatracker.ietf.org/doc/html/rfc9002)) in Go. It has support for HTTP/3 ([RFC 9114](https://datatracker.ietf.org/doc/html/rfc9114)), including QPACK ([RFC 9204](https://datatracker.ietf.org/doc/html/rfc9204)) and HTTP Datagrams ([RFC 9297](https://datatracker.ietf.org/doc/html/rfc9297)).
|
||||
|
||||
In addition to these base RFCs, it also implements the following RFCs:
|
||||
|
||||
* Unreliable Datagram Extension ([RFC 9221](https://datatracker.ietf.org/doc/html/rfc9221))
|
||||
* Datagram Packetization Layer Path MTU Discovery (DPLPMTUD, [RFC 8899](https://datatracker.ietf.org/doc/html/rfc8899))
|
||||
* QUIC Version 2 ([RFC 9369](https://datatracker.ietf.org/doc/html/rfc9369))
|
||||
* QUIC Event Logging using qlog
|
||||
* QUIC Stream Resets with Partial Delivery
|
||||
|
||||
Support for WebTransport over HTTP/3 is implemented in [webtransport-go](https://github.com/quic-go/webtransport-go).
|
||||
|
||||
Detailed documentation can be found on [quic-go.net](https://quic-go.net/docs/).
|
||||
|
||||
## FIPS 140-3
|
||||
|
||||
Starting with v0.60, quic-go supports use in FIPS 140-3 environments when built with Go 1.26 or newer, using Go standard library cryptography for the QUIC code paths relevant in FIPS mode.
|
||||
|
||||
## Projects using quic-go
|
||||
|
||||
| Project | Description |
|
||||
|---------|-------------|
|
||||
| [AdGuardHome](https://github.com/AdguardTeam/AdGuardHome) | Free and open source, powerful network-wide ads & trackers blocking DNS server. |
|
||||
| [caddy](https://github.com/caddyserver/caddy/) | Fast, multi-platform web server with automatic HTTPS |
|
||||
| [cloudflared](https://github.com/cloudflare/cloudflared) | A tunneling daemon that proxies traffic from the Cloudflare network to your origins |
|
||||
| [frp](https://github.com/fatedier/frp) | A fast reverse proxy to help you expose a local server behind a NAT or firewall to the internet |
|
||||
| [go-libp2p](https://github.com/libp2p/go-libp2p) | libp2p implementation in Go |
|
||||
| [Hysteria](https://github.com/apernet/hysteria) | A powerful, lightning fast and censorship resistant proxy |
|
||||
| [syncthing](https://github.com/syncthing/syncthing/) | Open Source Continuous File Synchronization |
|
||||
| [traefik](https://github.com/traefik/traefik) | The Cloud Native Application Proxy |
|
||||
|
||||
## Release Policy
|
||||
|
||||
quic-go always aims to support the latest two Go releases.
|
||||
|
||||
## Contributing
|
||||
|
||||
We are always happy to welcome new contributors! We have a number of self-contained issues that are suitable for first-time contributors, they are tagged with [help wanted](https://github.com/quic-go/quic-go/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22).
|
||||
|
||||
## License
|
||||
|
||||
The code is licensed under the MIT license.
|
||||
|
||||
---
|
||||
Source: https://raw.githubusercontent.com/quic-go/quic-go/master/README.md
|
||||
Downloaded: 2026-06-07
|
||||
@@ -0,0 +1 @@
|
||||
test
|
||||
Reference in New Issue
Block a user