2025-07-27 21:23:20 +00:00
|
|
|
# SmartRequest Architecture Hints
|
|
|
|
|
|
|
|
|
|
## Core Features
|
2024-04-14 03:54:39 +02:00
|
|
|
- supports http
|
|
|
|
|
- supports https
|
|
|
|
|
- supports unix socks
|
|
|
|
|
- supports formData
|
|
|
|
|
- supports file uploads
|
|
|
|
|
- supports best practice keepAlive
|
|
|
|
|
- dedicated functions for working with JSON request/response cycles
|
|
|
|
|
- written in TypeScript
|
|
|
|
|
- continuously updated
|
|
|
|
|
- uses node native http and https modules
|
|
|
|
|
- used in modules like @push.rocks/smartproxy and @api.global/typedrequest
|
2025-07-27 21:23:20 +00:00
|
|
|
|
|
|
|
|
## Architecture Overview (as of latest refactoring)
|
|
|
|
|
- The project is now structured with a clean separation between core functionality and API layers
|
|
|
|
|
- Core module (ts/core/) contains the essential HTTP request logic using Node.js http/https modules
|
|
|
|
|
- **Core always returns raw streams** - no parsing or body collection happens in the core request function
|
|
|
|
|
- Modern API (ts/modern/) provides a fluent, chainable interface with fetch-like Response objects
|
|
|
|
|
- Legacy API is maintained through a thin adapter layer for backward compatibility
|
|
|
|
|
|
|
|
|
|
## Key Components
|
|
|
|
|
|
|
|
|
|
### Core Module (ts/core/)
|
|
|
|
|
- `request.ts`: Core HTTP/HTTPS request logic with unix socket support and keep-alive agents
|
|
|
|
|
- `coreRequest()` always returns a raw Node.js IncomingMessage stream
|
|
|
|
|
- No response parsing or body collection happens here
|
|
|
|
|
- `response.ts`: SmartResponse class providing fetch-like API
|
|
|
|
|
- Methods like `json()`, `text()`, `arrayBuffer()` handle all parsing and body collection
|
|
|
|
|
- Response body is streamed and collected only when these methods are called
|
|
|
|
|
- Body can only be consumed once (throws error on second attempt)
|
|
|
|
|
- `types.ts`: Core TypeScript interfaces and types
|
|
|
|
|
- `plugins.ts`: Centralized dependencies
|
|
|
|
|
|
|
|
|
|
### Modern API
|
|
|
|
|
- SmartRequestClient: Fluent API with method chaining
|
|
|
|
|
- Returns SmartResponse objects with fetch-like methods
|
|
|
|
|
- Supports pagination, retries, timeouts, and various response types
|
|
|
|
|
|
|
|
|
|
### Binary Request Handling
|
|
|
|
|
- Binary requests are handled correctly when `responseType: 'binary'` is set
|
|
|
|
|
- Response body is kept as Buffer without string conversion
|
|
|
|
|
- No automatic transformations applied to binary data
|
|
|
|
|
|
|
|
|
|
### Legacy Compatibility
|
|
|
|
|
- All legacy functions (getJson, postJson, etc.) are maintained through adapter.ts
|
|
|
|
|
- Legacy API returns IExtendedIncomingMessage for backward compatibility
|
|
|
|
|
- Modern API can be accessed alongside legacy API
|
|
|
|
|
|
|
|
|
|
## Testing
|
|
|
|
|
- Use `pnpm test` to run all tests
|
|
|
|
|
- Modern API tests use the new SmartResponse methods (response.json(), response.text())
|
|
|
|
|
- Legacy API tests continue to use the body property directly
|
