AGENT SKILL
http-request
暂无简介
- License 许可
- MIT
- 最近更新
- 2026-04-13
- Stars
- ★ 0
- Forks
- 0
02 资源文件 3
- 脚本__tests__/handler.test.js1.4 KB
- 脚本handler.js9.9 KB
- 参考文档manifest.json7.4 KB
03 SKILL.md 正文
HTTP Request Skill
Make secure HTTP/HTTPS API calls with professional-grade features: automatic retries, timeout protection, response streaming, and credential masking.
Quick Start
const { execute } = require('./.agents/skills/http-request/handler');
// Simple GET request
const result = await execute({
method: 'GET',
url: 'https://api.github.com/users/github'
});
if (result.success) {
console.log('Status:', result.data.status);
console.log('Body:', result.data.body);
} else {
console.error('Error:', result.error.code, result.error.message);
}
Features
✅ Built-in Security
- SSL/TLS Verification: Always enabled. Prevents MITM attacks.
- Credential Masking: Auth headers are redacted from logs automatically.
- Size Limits: Prevents memory exhaustion (5MB request, 50MB response).
- Timeout Protection: Requests hang protection (default 30s).
✅ Reliability
- Automatic Retries: Exponential backoff for transient failures.
- Redirect Following: Smart handling of 3xx redirects (max 5).
- Error Recovery: Distinguishes between retryable and permanent errors.
- Compression Support: Handles gzip and deflate responses.
✅ Observability
- Structured Logging: Execution time, retry count, redirect count.
- Detailed Errors: Clear error codes (TIMEOUT, SSL_ERROR, etc.)
- Response Metadata: Size, headers, status codes.
Parameters
| Parameter | Type | Default | Required | Description |
|---|---|---|---|---|
| method | string | - | ✅ | HTTP method: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS |
| url | string | - | ✅ | Target URL (http or https). Max 2048 chars. |
| headers | object | {} | - | Custom HTTP headers |
| body | string|object | null | - | Request body (auto JSON stringified). Max 5MB. |
| timeout | number | 30000 | - | Timeout in milliseconds (100ms - 5min) |
| retry | object | - | - | Retry configuration (see below) |
| allowRedirects | boolean | true | - | Follow 3xx redirects (max 5) |
| validateStatus | boolean | true | - | Treat 4xx/5xx as errors |
Retry Configuration
retry: {
maxAttempts: 3, // 1-10 attempts
initialDelay: 1000, // Initial delay in ms (min 100)
backoffMultiplier: 2 // Exponential backoff (1-10)
}
Exponential Backoff Example (initialDelay=1000, multiplier=2):
- Attempt 1: Fail → Wait 1000ms
- Attempt 2: Fail → Wait 2000ms
- Attempt 3: Fail → Wait 4000ms
- Attempt 4: Give up
Response Format
Success Response
{
success: true,
data: {
status: 200,
statusText: "OK",
headers: {
"content-type": "application/json",
"content-length": "1234"
},
body: { /* parsed response */ },
size: 1234
},
error: null,
metadata: {
executionTime: 234, // milliseconds
timestamp: "2026-04-07T...",
retries: 0,
redirects: 0
}
}
Error Response
{
success: false,
data: null,
error: {
code: "NETWORK_TIMEOUT", // Error code
message: "Request timed out after 30000ms",
details: {
errorCode: "ETIMEDOUT", // Node.js error code
nodeError: "..."
}
},
metadata: {
executionTime: 30123,
timestamp: "2026-04-07T..."
}
}
Error Codes
| Code | Cause | Retryable | Notes |
|---|---|---|---|
| INVALID_URL | Malformed URL | No | Check URL format |
| NETWORK_TIMEOUT | Request exceeded timeout | Yes | Increase timeout if needed |
| NETWORK_ERROR | Connection failed | Yes | Check network/DNS |
| SSL_ERROR | Certificate verification failed | No | Check certificate or update CA |
| HTTP_ERROR | 4xx/5xx status code | Maybe | 5xx errors may retry |
| RESPONSE_TOO_LARGE | Response > 50MB | No | Reduce response size |
| INVALID_JSON | JSON parsing failed | No | Check response format |
| REDIRECT_LIMIT_EXCEEDED | Too many redirects | No | Use allowRedirects=false |
| UNSUPPORTED_PROTOCOL | Not http/https | No | Use http:// or https:// |
Examples
1. Simple GET
const result = await execute({
method: 'GET',
url: 'https://api.example.com/users'
});
console.log(result.data.body); // Array of users
2. POST with JSON Body
const result = await execute({
method: 'POST',
url: 'https://api.example.com/users',
headers: {
'Content-Type': 'application/json'
},
body: {
name: 'John',
email: 'john@example.com'
}
});
console.log(result.data.body.id); // New user ID
3. With Authentication
const result = await execute({
method: 'GET',
url: 'https://api.github.com/user',
headers: {
'Authorization': 'Bearer your-github-token',
'Accept': 'application/vnd.github.v3+json'
}
});
// Auth header is masked in logs: Authorization: ***MASKED***
console.log(result.data.body.login); // GitHub username
4. Custom Retry Strategy
const result = await execute({
method: 'GET',
url: 'https://flaky-api.example.com/data',
timeout: 10000,
retry: {
maxAttempts: 5, // Try up to 5 times
initialDelay: 500, // Start with 500ms delay
backoffMultiplier: 1.5 // 500ms → 750ms → 1.1s → 1.7s → 2.5s
}
});
console.log(result.metadata.retries); // Number of retries performed
5. No Retries (Fail Fast)
const result = await execute({
method: 'POST',
url: 'https://api.example.com/critical-operation',
body: { action: 'delete' },
retry: {
maxAttempts: 1 // No retries
}
});
6. Disable Redirect Following
const result = await execute({
method: 'HEAD',
url: 'https://example.com/old-page',
allowRedirects: false
});
// Get redirected location without following
if (result.data.status === 301) {
const newLocation = result.data.headers.location;
}
7. Ignore 4xx Errors
const result = await execute({
method: 'GET',
url: 'https://api.example.com/maybe-not-found',
validateStatus: false // Don't treat 404 as error
});
if (result.data.status === 404) {
console.log('Not found'); // success=true, but status=404
}
8. Large Response Handling
const result = await execute({
method: 'GET',
url: 'https://api.example.com/huge-dataset',
timeout: 60000 // Increase timeout for large responses
});
console.log(result.metadata.executionTime); // Time spent
console.log(result.data.size); // Response size in bytes
Security Best Practices
1. Always Use HTTPS
// Good
await execute({
method: 'GET',
url: 'https://api.example.com/data'
});
// Bad - Unencrypted
await execute({
method: 'GET',
url: 'http://api.example.com/data'
});
2. Don't Log Raw Responses with Credentials
// Good - Log only what you need
console.log('Status:', result.data.status);
// Bad - Could expose tokens/passwords
console.log('Full response:', JSON.stringify(result.data.body));
3. Validate URLs from User Input
// Good - Validate before use
function isAllowedUrl(url) {
const allowedDomains = ['api.example.com', 'cdn.example.com'];
const urlObj = new URL(url);
return allowedDomains.includes(urlObj.hostname);
}
if (isAllowedUrl(userProvidedUrl)) {
await execute({ method: 'GET', url: userProvidedUrl });
}
// Bad - Use user URL directly
await execute({ method: 'GET', url: userUrl });
4. Handle Errors Safely
// Good - Log context, not secrets
if (!result.success) {
console.error('API call failed:', {
code: result.error.code,
url: result.data?.headers?.url,
status: result.data?.status
});
}
// Bad - Could expose sensitive info
console.error('Request failed:', result);
5. Set Appropriate Timeouts
// Good - Reasonable timeouts for different operations
const shortOp = await execute({
method: 'GET',
url: 'https://api.example.com/health',
timeout: 5000 // 5s for health checks
});
const longOp = await execute({
method: 'POST',
url: 'https://api.example.com/process',
timeout: 120000 // 2min for processing
});
// Bad - No timeout (could hang forever)
await execute({
method: 'GET',
url: 'https://api.example.com/data'
// No timeout specified
});
Comparison with Other Tools
| Feature | http-request | curl | fetch API |
|---|---|---|---|
| Automatic retries | ✅ | ❌ | ❌ |
| Credential masking | ✅ | ❌ | ❌ |
| Timeout protection | ✅ | ⚠️ | ⚠️ |
| Response size limit | ✅ | ❌ | ❌ |
| Exponential backoff | ✅ | ❌ | ❌ |
| Structured errors | ✅ | ⚠️ | ⚠️ |
Troubleshooting
"NETWORK_TIMEOUT" Error
Cause: Request took longer than timeout period
Solutions:
- Increase timeout:
timeout: 60000(60s) - Check server health
- Reduce retry count:
maxAttempts: 1
"SSL_ERROR"
Cause: Certificate verification failed
Solutions:
- Ensure server has valid SSL certificate
- Check system time is correct
- Update CA certificates
- For development only: Set NODE_TLS_REJECT_UNAUTHORIZED=0
"ENOTFOUND" Network Error
Cause: DNS lookup failed
Solutions:
- Check DNS is working:
nslookup api.example.com - Verify URL is correct
- Check network connectivity
All Retries Exhausted
Cause: Server is down or returning 5xx errors
Solutions:
- Check server status
- Wait and retry manually
- Reduce retry count:
maxAttempts: 2 - Increase delay:
initialDelay: 5000
Performance Tips
- Reuse connections: HTTP keep-alive is automatic
- Reduce payload size: Use gzip compression if server supports
- Parallel requests: Use Promise.all() for multiple requests
- Cache responses: Implement caching layer if data is stable
- Monitor execution time: Check metadata.executionTime for slow requests
Related Skills
- data-transform: Parse and transform JSON responses
- logging: Log HTTP interactions
- file-operations: Save HTTP responses to disk
Version: 1.0.0
Last Updated: 2026-04-07