0
# HTTP Pipeline and Policies
1

2
Azure Core's HTTP pipeline provides a modular system for processing HTTP requests and responses through a chain of configurable policies. This architecture enables consistent behavior across all Azure SDK clients while allowing customization for specific service requirements.
3

4
## Core Pipeline Architecture
5

6
The pipeline processes requests through a series of policies before sending to the transport layer, then processes responses through the same policies in reverse order.
7

8
```python { .api }
9
from azure.core.pipeline import Pipeline, AsyncPipeline, PipelineRequest, PipelineResponse, PipelineContext
10
from typing import List
11

12
class Pipeline:
13
    """Synchronous HTTP pipeline."""
14
    def __init__(self, transport: HttpTransport, policies: Optional[List[HTTPPolicy]] = None): ...
15
    
16
    def run(self, request: PipelineRequest) -> PipelineResponse:
17
        """Execute the pipeline with the given request."""
18
        ...
19

20
class AsyncPipeline:
21
    """Asynchronous HTTP pipeline."""
22
    def __init__(self, transport: AsyncHttpTransport, policies: Optional[List[AsyncHTTPPolicy]] = None): ...
23
    
24
    async def run(self, request: PipelineRequest) -> PipelineResponse:
25
        """Execute the pipeline with the given request."""
26
        ...
27
```
28

29
### Pipeline Components
30

31
```python { .api }
32
class PipelineRequest:
33
    """Container for HTTP request and context."""
34
    def __init__(self, http_request: HttpRequest, context: PipelineContext): ...
35
    
36
    @property
37
    def http_request(self) -> HttpRequest: ...
38
    
39
    @property
40
    def context(self) -> PipelineContext: ...
41

42
class PipelineResponse:
43
    """Container for HTTP response and context."""
44
    def __init__(self, http_request: HttpRequest, http_response: HttpResponse, context: PipelineContext): ...
45
    
46
    @property
47
    def http_request(self) -> HttpRequest: ...
48
    
49
    @property
50
    def http_response(self) -> HttpResponse: ...
51
    
52
    @property
53
    def context(self) -> PipelineContext: ...
54

55
class PipelineContext(dict):
56
    """Execution context for pipeline processing."""
57
    def __init__(self, transport: HttpTransport, **kwargs): ...
58
```
59

60
## Base Policy Classes
61

62
All pipeline policies inherit from base policy classes that define the interface for request/response processing.
63

64
```python { .api }
65
from azure.core.pipeline.policies import HTTPPolicy, SansIOHTTPPolicy, AsyncHTTPPolicy
66
from abc import ABC, abstractmethod
67

68
class HTTPPolicy(ABC):
69
    """Base class for synchronous HTTP policies."""
70
    @abstractmethod
71
    def send(self, request: PipelineRequest) -> PipelineResponse: ...
72

73
class SansIOHTTPPolicy(ABC):
74
    """Base class for Sans-IO HTTP policies."""
75
    def on_request(self, request: PipelineRequest) -> None: ...
76
    def on_response(self, request: PipelineRequest, response: PipelineResponse) -> None: ...
77
    def on_exception(self, request: PipelineRequest) -> bool: ...
78

79
class AsyncHTTPPolicy(ABC):
80
    """Base class for asynchronous HTTP policies."""
81
    @abstractmethod
82
    async def send(self, request: PipelineRequest) -> PipelineResponse: ...
83
```
84

85
## Capabilities
86

87
### Retry Policies
88

89
Automatic retry logic with configurable strategies and backoff algorithms.
90

91
```python { .api }
92
from azure.core.pipeline.policies import RetryPolicy, AsyncRetryPolicy, RetryMode
93
from enum import Enum
94

95
class RetryMode(Enum):
96
    """Retry strategy modes."""
97
    Exponential = "exponential"
98
    Fixed = "fixed"
99

100
class RetryPolicy(HTTPPolicy):
101
    """Retry policy with exponential backoff."""
102
    def __init__(
103
        self,
104
        retry_total: int = 10,
105
        retry_connect: int = 3,
106
        retry_read: int = 3,
107
        retry_status: int = 3,
108
        retry_backoff_factor: float = 0.8,
109
        retry_backoff_max: int = 120,
110
        retry_mode: RetryMode = RetryMode.Exponential,
111
        **kwargs
112
    ): ...
113

114
class AsyncRetryPolicy(AsyncHTTPPolicy):
115
    """Async retry policy with exponential backoff."""
116
    def __init__(self, **kwargs): ...  # Same parameters as RetryPolicy
117

118
class RequestHistory:
119
    """Tracks retry attempt history."""
120
    def __init__(self, http_request: HttpRequest, **kwargs): ...
121
    
122
    @property
123
    def method(self) -> str: ...
124
    
125
    @property
126
    def url(self) -> str: ...
127
```
128

129
### Authentication Policies
130

131
Policies for handling various authentication mechanisms.
132

133
```python { .api }
134
from azure.core.pipeline.policies import BearerTokenCredentialPolicy, AsyncBearerTokenCredentialPolicy
135
from azure.core.pipeline.policies import AzureKeyCredentialPolicy, AzureSasCredentialPolicy
136

137
class BearerTokenCredentialPolicy(SansIOHTTPPolicy):
138
    """Bearer token authentication policy."""
139
    def __init__(self, credential: TokenCredential, *scopes: str, **kwargs): ...
140

141
class AsyncBearerTokenCredentialPolicy(AsyncHTTPPolicy):
142
    """Async bearer token authentication policy."""
143
    def __init__(self, credential: AsyncTokenCredential, *scopes: str, **kwargs): ...
144

145
class AzureKeyCredentialPolicy(SansIOHTTPPolicy):
146
    """API key authentication policy."""
147
    def __init__(self, credential: AzureKeyCredential, name: str, prefix: str = "", **kwargs): ...
148

149
class AzureSasCredentialPolicy(SansIOHTTPPolicy):
150
    """SAS authentication policy."""
151
    def __init__(self, credential: AzureSasCredential, **kwargs): ...
152
```
153

154
### Redirect and Response Policies
155

156
Policies for handling HTTP redirects and response processing.
157

158
```python { .api }
159
from azure.core.pipeline.policies import RedirectPolicy, AsyncRedirectPolicy, ContentDecodePolicy
160

161
class RedirectPolicy(HTTPPolicy):
162
    """HTTP redirect handling policy."""
163
    def __init__(self, permit_redirects: bool = True, redirect_max: int = 30, **kwargs): ...
164

165
class AsyncRedirectPolicy(AsyncHTTPPolicy):
166
    """Async HTTP redirect handling policy."""
167
    def __init__(self, **kwargs): ...  # Same parameters as RedirectPolicy
168

169
class ContentDecodePolicy(SansIOHTTPPolicy):
170
    """Automatic response content decoding policy."""
171
    def __init__(self, **kwargs): ...
172
```
173

174
### Headers and User Agent Policies
175

176
Policies for managing HTTP headers and user agent strings.
177

178
```python { .api }
179
from azure.core.pipeline.policies import HeadersPolicy, UserAgentPolicy
180

181
class HeadersPolicy(SansIOHTTPPolicy):
182
    """Custom headers policy."""
183
    def __init__(self, base_headers: Optional[Dict[str, str]] = None, **kwargs): ...
184

185
class UserAgentPolicy(SansIOHTTPPolicy):
186
    """User agent header policy."""
187
    def __init__(self, user_agent: Optional[str] = None, **kwargs): ...
188
    
189
    def add_user_agent(self, value: str) -> None:
190
        """Add a custom user agent value."""
191
        ...
192
```
193

194
### Logging and Monitoring Policies
195

196
Policies for request/response logging and network tracing.
197

198
```python { .api }
199
from azure.core.pipeline.policies import NetworkTraceLoggingPolicy, HttpLoggingPolicy, RequestIdPolicy
200

201
class NetworkTraceLoggingPolicy(SansIOHTTPPolicy):
202
    """Network request/response tracing policy."""
203
    def __init__(self, logging_enable: bool = False, **kwargs): ...
204

205
class HttpLoggingPolicy(SansIOHTTPPolicy):
206
    """HTTP request/response logging policy."""
207
    def __init__(self, logger: Optional[logging.Logger] = None, **kwargs): ...
208

209
class RequestIdPolicy(SansIOHTTPPolicy):
210
    """Request ID generation policy."""
211
    def __init__(self, **kwargs): ...
212
```
213

214
### Advanced Policies
215

216
Specialized policies for distributed tracing, proxy support, and custom hooks.
217

218
```python { .api }
219
from azure.core.pipeline.policies import DistributedTracingPolicy, ProxyPolicy, CustomHookPolicy
220
from azure.core.pipeline.policies import SensitiveHeaderCleanupPolicy
221

222
class DistributedTracingPolicy(SansIOHTTPPolicy):
223
    """Distributed tracing policy with OpenTelemetry support."""
224
    def __init__(self, **kwargs): ...
225

226
class ProxyPolicy(SansIOHTTPPolicy):
227
    """HTTP proxy configuration policy."""
228
    def __init__(self, proxies: Optional[Dict[str, str]] = None, **kwargs): ...
229

230
class CustomHookPolicy(SansIOHTTPPolicy):
231
    """Custom request/response hook policy."""
232
    def __init__(self, **kwargs): ...
233

234
class SensitiveHeaderCleanupPolicy(SansIOHTTPPolicy):
235
    """Removes sensitive headers from logs and traces."""
236
    def __init__(self, **kwargs): ...
237
```
238

239
## Usage Examples
240

241
### Basic Pipeline Configuration
242

243
```python
244
from azure.core.pipeline import Pipeline
245
from azure.core.pipeline.policies import RetryPolicy, UserAgentPolicy, HeadersPolicy
246
from azure.core.pipeline.transport import RequestsTransport
247

248
# Create transport
249
transport = RequestsTransport()
250

251
# Configure policies
252
policies = [
253
    UserAgentPolicy(user_agent="MyApp/1.0"),
254
    HeadersPolicy(base_headers={"Accept": "application/json"}),
255
    RetryPolicy(retry_total=5),
256
]
257

258
# Create pipeline
259
pipeline = Pipeline(transport=transport, policies=policies)
260

261
# Create and send request
262
from azure.core.pipeline.transport import HttpRequest
263
from azure.core.pipeline import PipelineRequest, PipelineContext
264

265
request = HttpRequest("GET", "https://api.example.com/data")
266
pipeline_request = PipelineRequest(request, PipelineContext(transport))
267
response = pipeline.run(pipeline_request)
268

269
print(f"Status: {response.http_response.status_code}")
270
```
271

272
### Custom Pipeline Policy
273

274
```python
275
from azure.core.pipeline.policies import SansIOHTTPPolicy
276

277
class CustomHeaderPolicy(SansIOHTTPPolicy):
278
    """Adds custom headers to all requests."""
279
    
280
    def __init__(self, custom_header_value, **kwargs):
281
        super().__init__(**kwargs)
282
        self.custom_value = custom_header_value
283
    
284
    def on_request(self, request):
285
        request.http_request.headers["X-Custom-Header"] = self.custom_value
286
        
287
    def on_response(self, request, response):
288
        # Process response if needed
289
        pass
290

291
# Use custom policy
292
custom_policy = CustomHeaderPolicy("my-value")
293
policies = [custom_policy, RetryPolicy()]
294
pipeline = Pipeline(transport=transport, policies=policies)
295
```
296

297
### Async Pipeline Usage
298

299
```python
300
import asyncio
301
from azure.core.pipeline import AsyncPipeline
302
from azure.core.pipeline.policies import AsyncRetryPolicy
303
from azure.core.pipeline.transport import AioHttpTransport
304

305
async def async_pipeline_example():
306
    # Create async transport and policies
307
    transport = AioHttpTransport()
308
    policies = [AsyncRetryPolicy(retry_total=3)]
309
    
310
    # Create async pipeline
311
    pipeline = AsyncPipeline(transport=transport, policies=policies)
312
    
313
    # Create and send request
314
    request = HttpRequest("GET", "https://api.example.com/data")
315
    pipeline_request = PipelineRequest(request, PipelineContext(transport))
316
    response = await pipeline.run(pipeline_request)
317
    
318
    print(f"Status: {response.http_response.status_code}")
319

320
# asyncio.run(async_pipeline_example())
321
```
322

323
### Advanced Policy Configuration
324

325
```python
326
from azure.core.pipeline.policies import (
327
    RetryPolicy, RetryMode, BearerTokenCredentialPolicy,
328
    DistributedTracingPolicy, HttpLoggingPolicy
329
)
330

331
# Configure advanced retry policy
332
retry_policy = RetryPolicy(
333
    retry_total=10,
334
    retry_backoff_factor=1.0,
335
    retry_backoff_max=60,
336
    retry_mode=RetryMode.Exponential,
337
    retry_on_status_codes=[429, 500, 502, 503, 504]
338
)
339

340
# Configure authentication
341
# auth_policy = BearerTokenCredentialPolicy(credential, "https://api.example.com/.default")
342

343
# Configure tracing and logging
344
tracing_policy = DistributedTracingPolicy()
345
logging_policy = HttpLoggingPolicy()
346

347
# Combine all policies
348
policies = [
349
    # auth_policy,
350
    retry_policy,
351
    tracing_policy,
352
    logging_policy,
353
]
354
```
355

356
## Policy Ordering
357

358
The order of policies in the pipeline is crucial for proper request/response processing:
359

360
1. **Authentication policies** - Should be early to add auth headers
361
2. **Header policies** - Add custom headers before other processing
362
3. **Retry policies** - Handle retries for the entire request
363
4. **Redirect policies** - Handle redirects before content processing
364
5. **Content policies** - Process request/response content
365
6. **Logging policies** - Should be last to capture final request state
366

367
## Best Practices
368

369
### Policy Design
370

371
- Use `SansIOHTTPPolicy` for stateless policies that only modify headers/metadata
372
- Use `HTTPPolicy` or `AsyncHTTPPolicy` for policies that need to control request flow
373
- Keep policies focused on a single responsibility
374
- Make policies configurable through constructor parameters
375

376
### Error Handling
377

378
- Implement proper exception handling in custom policies
379
- Use `on_exception` method in Sans-IO policies for cleanup
380
- Allow exceptions to bubble up unless the policy can handle them completely
381

382
### Performance Considerations
383

384
- Minimize policy overhead for request/response processing
385
- Cache expensive computations across requests when possible
386
- Use async policies with async transports for optimal performance
387
- Consider policy ordering impact on performance