feat(diagnostics): Improve error diagnostics usability

README.org

@@ -1,6 +1,6 @@
 #+TITLE: zig-curl
 #+DATE: 2023-09-16T23:16:15+0800
-#+LASTMOD: 2025-10-17T09:10:36+0800
+#+LASTMOD: 2026-03-08T11:50:51+0800
 #+OPTIONS: toc:nil num:nil
 #+STARTUP: content
 
@@ -61,6 +61,23 @@ pub fn main() !void {
 
 Check [[file:examples]] for more examples.
 
+** Diagnostics
+When a curl operation fails, it returns a generic =error.Curl=. To get more detailed information, you can use the =diagnostics= field in =Easy= or =Multi=.
+
+#+begin_src zig
+    var easy = try curl.Easy.init(.{ ... });
+    defer easy.deinit();
+
+    easy.perform() catch |err| {
+        if (err == error.Curl) {
+            if (easy.diagnostics.getMessage()) |msg| {
+                std.log.err("curl failed: {s}", .{msg});
+            }
+        }
+        return err;
+    };
+#+end_src
+
 * Documentation
 See https://jiacai2050.github.io/zig-curl/
 

examples/header.zig

@@ -33,7 +33,7 @@ fn iterateRedirectedHeaders(easy: *Easy) !void {
     try easy.setFollowLocation(true);
     const resp = try easy.fetch("https://edgebin.liujiacai.net/redirect/2", .{});
 
-    var diagnostics: Easy.Diagnostics = .{};
+    var diagnostics: curl.Diagnostics = .{};
     const redirects = try resp.getRedirectCount(&diagnostics);
     try std.testing.expectEqual(redirects, 2);
 

examples/multi.zig

@@ -25,10 +25,13 @@ pub fn main() !void {
     defer if (gpa.deinit() != .ok) @panic("leak");
     const allocator = gpa.allocator();
 
-    var diagnostics: Multi.Diagnostics = .{};
-
-    const multi = try Multi.init(&diagnostics);
-    defer multi.deinit();
+    var multi = try Multi.init();
+    defer multi.deinit() catch |e| {
+        std.debug.print("multi handle deinit failed, err:{any}\n", .{e});
+        if (multi.diagnostics.getMessage()) |msg| {
+            std.debug.print("Diagnostics: {s}\n", .{msg});
+        }
+    };
 
     var wtr1 = std.Io.Writer.Allocating.init(allocator);
     defer wtr1.deinit();
@@ -67,16 +70,16 @@ pub fn main() !void {
         }
 
         // check that the request was successful
-        try checkCode(info.msg.data.result, &diagnostics);
+        try checkCode(info.msg.data.result, &multi.diagnostics);
 
         // Read the HTTP status code
         var status_code: c_long = 0;
-        try checkCode(c.curl_easy_getinfo(easy_handle, c.CURLINFO_RESPONSE_CODE, &status_code), &diagnostics);
+        try checkCode(c.curl_easy_getinfo(easy_handle, c.CURLINFO_RESPONSE_CODE, &status_code), &multi.diagnostics);
         std.debug.print("Response Code: {any}\n", .{status_code});
 
         // Get the private data (buffer) associated with this handle
         var private_data: ?*anyopaque = null;
-        try checkCode(c.curl_easy_getinfo(easy_handle, c.CURLINFO_PRIVATE, &private_data), &diagnostics);
+        try checkCode(c.curl_easy_getinfo(easy_handle, c.CURLINFO_PRIVATE, &private_data), &multi.diagnostics);
         const writer: *Writer = @ptrCast(@alignCast(private_data.?));
 
         std.debug.print("Response body: {s}\n", .{writer.buffered()});

src/Multi.zig

@@ -19,50 +19,50 @@ pub const Diagnostics = errors.Diagnostics;
 const Self = @This();
 
 multi: *c.CURLM,
-diagnostics: ?*Diagnostics,
+diagnostics: Diagnostics,
 
-pub fn init(diagnostics: ?*Diagnostics) !Self {
+pub fn init() !Self {
     const core = c.curl_multi_init();
     if (core == null) {
         return error.InitMulti;
     }
     return .{
         .multi = core.?,
-        .diagnostics = diagnostics,
+        .diagnostics = .{},
     };
 }
 
-pub fn deinit(self: Self) void {
-    _ = self;
+pub fn deinit(self: *Self) !void {
+    return checkMCode(c.curl_multi_cleanup(self.multi), &self.diagnostics);
 }
 
 /// Adds the easy handle to the multi_handle.
 /// https://curl.se/libcurl/c/curl_multi_add_handle.html
-pub fn addHandle(self: Self, easy: *Easy) !void {
+pub fn addHandle(self: *Self, easy: *Easy) !void {
     try easy.setCommonOpts();
-    return checkMCode(c.curl_multi_add_handle(self.multi, easy.handle), self.diagnostics);
+    return checkMCode(c.curl_multi_add_handle(self.multi, easy.handle), &self.diagnostics);
 }
 
 /// Removes a given easy_handle from the multi_handle.
 /// https://curl.se/libcurl/c/curl_multi_remove_handle.html
-pub fn removeHandle(self: Self, handle: *c.CURL) !void {
-    return checkMCode(c.curl_multi_remove_handle(self.multi, handle), self.diagnostics);
+pub fn removeHandle(self: *Self, handle: *c.CURL) !void {
+    return checkMCode(c.curl_multi_remove_handle(self.multi, handle), &self.diagnostics);
 }
 
 /// Performs transfers on all the added handles that need attention in a non-blocking fashion.
 /// Returns the number of handles that still transfer data. When that reaches zero, all transfers are done.
 /// https://curl.se/libcurl/c/curl_multi_perform.html
-pub fn perform(self: Self) !c_int {
+pub fn perform(self: *Self) !c_int {
     var still_running: c_int = undefined;
-    try checkMCode(c.curl_multi_perform(self.multi, &still_running), self.diagnostics);
+    try checkMCode(c.curl_multi_perform(self.multi, &still_running), &self.diagnostics);
 
     return still_running;
 }
 
 /// Polls all file descriptors used by the curl easy handles contained in the given multi handle set.
 /// Return the number of file descriptors on which there is activity.
 /// https://curl.se/libcurl/c/curl_multi_poll.html
-pub fn poll(self: Self, extra_fds: ?[]c.curl_waitfd, timeout_ms: c_int) !c_int {
+pub fn poll(self: *Self, extra_fds: ?[]c.curl_waitfd, timeout_ms: c_int) !c_int {
     var num_fds: c_int = undefined;
     var fds: ?[*]c.curl_waitfd = null;
     var fd_len: c_uint = 0;
@@ -71,15 +71,15 @@ pub fn poll(self: Self, extra_fds: ?[]c.curl_waitfd, timeout_ms: c_int) !c_int {
         fd_len = @intCast(v.len);
     }
 
-    try checkMCode(c.curl_multi_poll(self.multi, fds, fd_len, timeout_ms, &num_fds), self.diagnostics);
+    try checkMCode(c.curl_multi_poll(self.multi, fds, fd_len, timeout_ms, &num_fds), &self.diagnostics);
     return num_fds;
 }
 
 /// Wakes up a sleeping curl_multi_poll call that is currently (or is about to be) waiting for activity or a timeout.
 /// This function can be called from any thread.
 /// https://curl.se/libcurl/c/curl_multi_wakeup.html
-pub fn wakeup(self: Self) !void {
-    try checkMCode(c.curl_multi_wakeup(self.multi), self.diagnostics);
+pub fn wakeup(self: *Self) !void {
+    try checkMCode(c.curl_multi_wakeup(self.multi), &self.diagnostics);
 }
 
 pub const Info = struct {
@@ -89,7 +89,7 @@ pub const Info = struct {
 
 /// Ask the multi handle if there are any messages from the individual transfers.
 /// https://curl.se/libcurl/c/curl_multi_info_read.html
-pub fn readInfo(self: Self) !Info {
+pub fn readInfo(self: *Self) !Info {
     var msgs_in_queue: c_int = undefined;
 
     const msg = c.curl_multi_info_read(self.multi, &msgs_in_queue);

src/errors.zig

@@ -39,6 +39,15 @@ pub const Diagnostics = struct {
         /// https://curl.se/libcurl/c/libcurl-errors.html#CURLMcode
         m_code: c.CURLMcode,
     } = null,
+
+    /// Returns a human-readable error message based on the error code.
+    pub fn getMessage(self: Diagnostics) ?[]const u8 {
+        const error_code = self.error_code orelse return null;
+        return switch (error_code) {
+            .code => |code| std.mem.span(c.curl_easy_strerror(code)),
+            .m_code => |m_code| std.mem.span(c.curl_multi_strerror(m_code)),
+        };
+    }
 };
 
 pub fn checkCode(code: c.CURLcode, diagnostics: ?*Diagnostics) !void {
@@ -48,9 +57,6 @@ pub fn checkCode(code: c.CURLcode, diagnostics: ?*Diagnostics) !void {
 
     if (diagnostics) |diag| diag.error_code = .{ .code = code };
 
-    // https://curl.se/libcurl/c/libcurl-errors.html
-    std.log.debug("curl err code:{d}, msg:{s}\n", .{ code, c.curl_easy_strerror(code) });
-
     return error.Curl;
 }
 
@@ -61,11 +67,5 @@ pub fn checkMCode(code: c.CURLMcode, diagnostics: ?*Diagnostics) !void {
 
     if (diagnostics) |diag| diag.error_code = .{ .m_code = code };
 
-    // https://curl.se/libcurl/c/libcurl-errors.html
-    std.log.debug("curlm err code:{d}, msg:{s}\n", .{
-        code,
-        c.curl_multi_strerror(code),
-    });
-
     return error.Curl;
 }