|
| 1 | +## Project Status |
| 2 | + |
| 3 | +**This library has matured significantly and is now feature-complete for most HTTP client use cases.** The core functionality described in the original roadmap has been implemented and is being used successfully in production JKI projects. |
| 4 | + |
1 | 5 | ## Guiding Principles |
2 | 6 |
|
3 | | -* **Experimental Stage:** This library is experimental. The API is subject to change. |
4 | | -* **No Deprecation / Breaking Changes Welcome:** We will refactor and replace functionality directly. We will not maintain deprecated functions for backward compatibility. Breaking changes are expected and encouraged in pursuit of a better API. |
5 | | -* **Async-Only Core:** The Rust library will **only** expose non-blocking, asynchronous functions. Synchronous (blocking) wrappers can be built in the calling application (e.g., LabVIEW) if needed. This means all existing synchronous functions will be **removed**. |
6 | | - |
7 | | -## Potential Improvements |
8 | | - |
9 | | -Here is a summary of potential improvements, categorized for clarity: |
10 | | - |
11 | | -### 1. Client-Wide Configuration |
12 | | - |
13 | | -Currently, our `reqwest_client_new` function creates a client with default settings. Many applications need to customize the client's behavior for all requests. |
14 | | - |
15 | | -* **Timeouts:** This is the most critical missing feature. A request could hang indefinitely, freezing the calling application. We should allow setting **connection timeouts** (how long to wait to connect to the server) and **request timeouts** (a total time limit for the entire request). |
16 | | -* **SSL Verification Control:** Allow disabling SSL certificate verification (as an explicit opt-in) for use with self-signed certificates. |
17 | | -* **Default Headers:** Instead of adding a header to every single call, users often need to set a header (like an `Authorization` or `User-Agent` header) that is automatically sent with every request made by that client. |
18 | | -* **Proxy Configuration:** Many corporate or specific network environments require routing traffic through an HTTP or SOCKS proxy. |
19 | | -* **Redirect Policy:** We could expose settings to control how many redirects to follow before giving up. |
20 | | - |
21 | | -### 2. Richer Request Customization |
22 | | - |
23 | | -Our current functions are specific to one method and one body type (e.g., `reqwest_post_json`). This leads to a lot of functions and doesn't cover all needs. |
24 | | - |
25 | | -* **Flexible Headers:** The `reqwest_get_with_header` function is a good start, but it only works for GET requests and only allows one header. A better approach would be to create a "header map" object that can be built up by the user and attached to *any* request (`GET`, `POST`, `PUT`, etc.). |
26 | | -* **More Body Types:** We should support sending raw binary data for uploads. |
27 | | -* **Multipart Forms:** A very common use case is uploading files using a `multipart/form-data` request, which is not currently possible. |
28 | | -* **Authentication:** We could add convenience functions for common authentication schemes like Basic Authentication (`user:password`) and Bearer Token authentication. |
29 | | -* **Query Parameters:** Building URLs with query strings by hand is error-prone. We could provide a way to add key-value query parameters to a request in a structured way. |
30 | | - |
31 | | -### 3. More Detailed Response Information |
32 | | - |
33 | | -Right now, we can only get the response body. A lot of valuable information is being missed. |
34 | | - |
35 | | -* **Get Response Headers:** Users often need to read headers from the server's response (e.g., to check the `Content-Type`, read rate-limiting information, or get session cookies). |
36 | | -* **Get Status Code from Response:** The `reqwest_get_status` function makes a whole new request just to get the status. We should be able to get the status code from any completed request (both blocking and async) without having to make a second call. |
37 | | - |
38 | | -### 4. Broader Asynchronous Support |
39 | | - |
40 | | -Our async functionality is powerful but currently limited to `GET` requests. |
41 | | - |
42 | | -* **Async for All Methods:** We should add asynchronous, non-blocking versions of `POST`, `PUT`, and `DELETE` requests, including support for file streaming uploads and downloads. |
43 | | - |
44 | | -## Priorities |
45 | | - |
46 | | -This plan is organized into phases. Each phase builds on the previous one. |
47 | | - |
48 | | -### Phase 1: Foundational Stability & Flexibility |
49 | | -* **Goal:** Rework the client creation to be flexible and remove all synchronous functions. |
50 | | -* **Approach:** We will implement a **builder pattern** for client creation and delete all blocking functions. |
51 | | -* **Tasks:** |
52 | | - - [ ] **Implement Client Builder:** |
53 | | - - `client_builder_new()` |
54 | | - - `client_builder_timeout(builder, connect_secs, request_secs)` |
55 | | - - `client_builder_danger_accept_invalid_certs(builder, accept)` |
56 | | - - `client_builder_default_headers(builder, headers)` (Depends on Header Map). |
57 | | - - `client_builder_build(builder)`. |
58 | | - - [ ] **Implement Reusable Header Map:** |
59 | | - - `headers_new()` |
60 | | - - `headers_add(map, key, value)` |
61 | | - - `headers_free(map)` |
62 | | - - [ ] **Cull Synchronous Functions:** |
63 | | - - Remove all blocking functions (`reqwest_get`, `reqwest_post_json`, etc.). |
64 | | - - Refactor `async_get_start` to accept an optional Header Map pointer for per-request headers. |
65 | | - - [ ] **Update All Tests:** |
66 | | - - Remove all tests for synchronous functions. |
67 | | - - Update the remaining async tests to use the new client builder and header map functionality. |
68 | | - |
69 | | -### Phase 2: Rich Response Objects (Major API Improvement) |
70 | | -* **Goal:** Provide users with access to crucial response data like status codes and headers from completed async calls. |
71 | | -* **Tasks:** |
72 | | - - [ ] **Introduce a `Response` Object:** This object will encapsulate the final state of a request (success or error). |
73 | | - - [ ] **Refactor Async Result Function:** The `async_get_response` function will be **replaced** by `async_take_result(request_id)`, which returns a pointer to the `Response` object. |
74 | | - - [ ] **Create `Response` Accessors:** |
75 | | - - `response_status(response)` |
76 | | - - `response_headers(response)` (returns a read-only Header Map) |
77 | | - - `response_body_copy(response, ...)` |
78 | | - - `response_error_string_copy(response, ...)` |
79 | | - - `response_free(response)` |
80 | | - |
81 | | -### Phase 3: Expand Asynchronous Operations |
82 | | -* **Goal:** Provide a full suite of asynchronous HTTP methods, as they are now the only methods available. |
83 | | -* **Tasks:** |
84 | | - - [ ] **Async POST, PUT, DELETE:** Create `async_post_start`, `async_put_start`, etc., supporting various body types (JSON, form, binary). |
85 | | - |
86 | | -### Phase 4: Advanced Features & Ergonomics |
87 | | -* **Goal:** Add support for more complex use cases and provide quality-of-life improvements. |
88 | | -* **Tasks:** |
89 | | - - [ ] **Authentication Helpers:** Add convenience functions for Basic and Bearer token authentication. |
90 | | - - [ ] **Multipart Forms:** Implement `multipart/form-data` requests. |
91 | | - - [ ] **Query Parameter Builder:** Add a structured way to add URL query parameters. |
92 | | - - [ ] **Proxy & Redirect Configuration:** Expose client-level settings for proxies and redirect policies. |
| 7 | +* **Production Ready:** This library has evolved from experimental to production-ready. The core API is stable, though minor enhancements may still be added. |
| 8 | +* **Async-Only Core:** The Rust library **only** exposes non-blocking, asynchronous functions. Synchronous (blocking) wrappers are built in the LabVIEW layer when needed. |
| 9 | +* **Comprehensive LabVIEW Integration:** Full LabVIEW wrapper library with 70+ VIs providing a native LabVIEW experience. |
| 10 | + |
| 11 | +## Implemented Features |
| 12 | + |
| 13 | +The following features have been successfully implemented and are available in the current version: |
| 14 | + |
| 15 | +### ✅ **Client-Wide Configuration - COMPLETED** |
| 16 | + |
| 17 | +- **✅ Timeouts:** Connection timeouts and request timeouts are fully supported |
| 18 | +- **✅ SSL Verification Control:** Can disable SSL certificate verification with `client_builder_danger_accept_invalid_certs` |
| 19 | +- **✅ Default Headers:** Client builder supports setting default headers for all requests |
| 20 | +- **✅ Proxy Configuration:** Comprehensive proxy support including HTTP and SOCKS proxies |
| 21 | +- **✅ Redirect Policy:** Configurable redirect handling |
| 22 | + |
| 23 | +### ✅ **Rich Request Customization - COMPLETED** |
| 24 | + |
| 25 | +- **✅ Flexible Headers:** Full header map support for any HTTP method with `headers_create/add/destroy` |
| 26 | +- **✅ Multiple Body Types:** Support for JSON, form data, and raw binary data |
| 27 | +- **✅ Authentication:** Built-in Basic and Bearer token authentication methods |
| 28 | +- **✅ Query Parameters:** Structured query parameter building with `request_builder_query` |
| 29 | +- **✅ All HTTP Methods:** GET, POST, PUT, DELETE with full customization |
| 30 | + |
| 31 | +### ✅ **Detailed Response Information - COMPLETED** |
| 32 | + |
| 33 | +- **✅ Response Headers:** Full access to response headers with `request_read_response_headers` |
| 34 | +- **✅ Status Codes:** Direct status code access with `request_read_response_status` |
| 35 | +- **✅ Response Bodies:** Complete response body handling with `request_read_response_body` |
| 36 | +- **✅ Error Handling:** Comprehensive error reporting with `request_read_transport_error` |
| 37 | + |
| 38 | +### ✅ **Full Asynchronous Support - COMPLETED** |
| 39 | + |
| 40 | +- **✅ Async All Methods:** Non-blocking versions of all HTTP methods (GET, POST, PUT, DELETE) |
| 41 | +- **✅ Progress Tracking:** Real-time progress information for requests |
| 42 | +- **✅ Request Cancellation:** Ability to cancel in-flight requests |
| 43 | +- **✅ File Downloads:** Direct-to-file streaming downloads |
| 44 | + |
| 45 | +## Remaining Potential Enhancements |
| 46 | + |
| 47 | +While the core functionality is complete, these features could be added in future versions: |
| 48 | + |
| 49 | +### 1. **Multipart Form Support** (Not Yet Implemented) |
| 50 | + |
| 51 | +The main feature not yet implemented from the original roadmap: |
| 52 | + |
| 53 | +* **Multipart Forms:** Support for `multipart/form-data` requests for file uploads is not currently available |
| 54 | + |
| 55 | +### 2. **Additional Convenience Features** (Future Enhancements) |
| 56 | + |
| 57 | +* **Enhanced File Upload API:** While binary data uploads work, a more specialized file upload API could be added |
| 58 | +* **WebSocket Support:** Could add WebSocket client capabilities |
| 59 | +* **HTTP/3 Support:** Future reqwest versions may add HTTP/3, which could be exposed |
| 60 | +* **Advanced Compression:** Additional compression algorithms beyond the current support |
| 61 | +* **Request Retry Logic:** Built-in retry mechanisms with backoff strategies |
| 62 | + |
| 63 | +## Implementation History |
| 64 | + |
| 65 | +### ✅ Phase 1: Foundational Stability & Flexibility - **COMPLETED** |
| 66 | +* **Goal:** ✅ Implemented builder pattern for client creation and removed all synchronous functions |
| 67 | +* **Status:** **COMPLETED** - Full client builder API with timeouts, SSL control, headers, and proxy support |
| 68 | +* **Implementation:** |
| 69 | + - ✅ Complete Client Builder API (`client_builder_*` functions) |
| 70 | + - ✅ Reusable Header Map (`headers_*` functions) |
| 71 | + - ✅ All synchronous functions removed - library is async-only |
| 72 | + - ✅ Comprehensive test coverage |
| 73 | + |
| 74 | +### ✅ Phase 2: Rich Response Objects - **COMPLETED** |
| 75 | +* **Goal:** ✅ Provide users with access to response data like status codes and headers |
| 76 | +* **Status:** **COMPLETED** - Full response object access implemented |
| 77 | +* **Implementation:** |
| 78 | + - ✅ Complete Response access via `request_*` functions |
| 79 | + - ✅ Status code access (`request_read_response_status`) |
| 80 | + - ✅ Header access (`request_read_response_headers`) |
| 81 | + - ✅ Body access (`request_read_response_body`) |
| 82 | + - ✅ Error handling (`request_read_transport_error`) |
| 83 | + |
| 84 | +### ✅ Phase 3: Expand Asynchronous Operations - **COMPLETED** |
| 85 | +* **Goal:** ✅ Provide full suite of asynchronous HTTP methods |
| 86 | +* **Status:** **COMPLETED** - All HTTP methods available with full customization |
| 87 | +* **Implementation:** |
| 88 | + - ✅ Async POST, PUT, DELETE via unified request builder pattern |
| 89 | + - ✅ JSON body support (`request_builder_json`) |
| 90 | + - ✅ Form data support (`request_builder_form`) |
| 91 | + - ✅ Raw binary data support (`request_builder_body`) |
| 92 | + - ✅ File output support (`request_builder_set_output_file`) |
| 93 | + |
| 94 | +### ✅ Phase 4: Advanced Features & Ergonomics - **MOSTLY COMPLETED** |
| 95 | +* **Goal:** ✅ Support for complex use cases and quality-of-life improvements |
| 96 | +* **Status:** **MOSTLY COMPLETED** - Most advanced features implemented |
| 97 | +* **Implementation:** |
| 98 | + - ✅ Authentication Helpers (`request_builder_basic_auth`, `request_builder_bearer_auth`) |
| 99 | + - ❌ **Multipart Forms:** Not yet implemented - this is the main remaining feature |
| 100 | + - ✅ Query Parameter Builder (`request_builder_query`) |
| 101 | + - ✅ Proxy & Redirect Configuration (extensive proxy support in client builder) |
| 102 | + |
| 103 | +## Current Development Status |
| 104 | + |
| 105 | +**The library is production-ready and feature-complete for most HTTP client use cases.** It includes: |
| 106 | + |
| 107 | +- **1200+ lines of FFI implementation** providing comprehensive HTTP client functionality |
| 108 | +- **70+ LabVIEW VIs** offering a native LabVIEW programming experience |
| 109 | +- **Comprehensive test suite** (some tests currently fail due to network connectivity to httpbin.org, not missing functionality) |
| 110 | +- **Cross-platform support** with pre-built binaries for Windows, Linux, and macOS |
| 111 | +- **Production use** in multiple JKI projects |
| 112 | + |
| 113 | +## Next Steps |
| 114 | + |
| 115 | +1. **Multipart Forms:** The primary remaining feature to implement for full HTTP client coverage |
| 116 | +2. **Test Infrastructure:** Consider using a local test server instead of external httpbin.org dependency |
| 117 | +3. **Documentation:** Continue improving developer and user documentation |
| 118 | +4. **VI Package Release:** Create official VI Package for easier distribution |
| 119 | + |
| 120 | +*Last Updated: December 2024* |
0 commit comments