py/stream: Use detailed error strings for TLS sockets.

DvdGiessen · dpgeorge · commit 71866edc132b · 2026-02-07T16:34:20.000+11:00
Both mbedTLS and axTLS have support for producing more detailed error
strings.  However, these are not used if the error is raised in stream
protocol functions (read/write/ioctl).

This commit adds support for more detailed error messages from streams.
Under the hood it's using a new MP_STREAM_RAISE_ERROR ioctl request to pass
the error code back to the stream implementation which can raise a more
detailed error.  If the ioctl is not implemented, we fall back to the old
behaviour and raise an OSError with the error code.

Currently the detailed messages are only implemented for TLS sockets since
those already had helper functions for raising detailed exceptions, but can
be easily implemented in any other stream.

Signed-off-by: Daniël van de Giessen &lt;daniel@dvdgiessen.nl&gt;
diff --git a/extmod/modtls_axtls.c b/extmod/modtls_axtls.c
@@ -390,6 +390,12 @@ static mp_uint_t ssl_socket_ioctl(mp_obj_t o_in, mp_uint_t request, uintptr_t ar
         ssl_ctx_free(self->ssl_ctx);
         self->ssl_sock = NULL;
     }
+    #if MICROPY_STREAMS_DELEGATE_ERROR
+    else if (request == MP_STREAM_RAISE_ERROR) {
+        // Raise error with detailed error string
+        ssl_raise_error((int)arg);
+    }
+    #endif
 
     if (self->sock == MP_OBJ_NULL) {
         // Underlying socket may be null if the constructor raised an exception.
diff --git a/extmod/modtls_mbedtls.c b/extmod/modtls_mbedtls.c
@@ -870,7 +870,14 @@ static mp_uint_t socket_ioctl(mp_obj_t o_in, mp_uint_t request, uintptr_t arg, i
                 }
             }
         }
-    } else {
+    }
+    #if MICROPY_STREAMS_DELEGATE_ERROR
+    else if (request == MP_STREAM_RAISE_ERROR) {
+        // Raise error with detailed error string
+        mbedtls_raise_error((int)arg);
+    }
+    #endif
+    else {
         // Unsupported ioctl.
         *errcode = MP_EINVAL;
         return MP_STREAM_ERROR;
diff --git a/py/mpconfig.h b/py/mpconfig.h
@@ -1097,6 +1097,12 @@ typedef time_t mp_timestamp_t;
 #define MICROPY_STREAMS_POSIX_API (0)
 #endif
 
+// Whether to delegate error raising to stream implementations using the
+// MP_STREAM_RAISE_ERROR ioctl to support raising more detailed messages.
+#ifndef MICROPY_STREAMS_DELEGATE_ERROR
+#define MICROPY_STREAMS_DELEGATE_ERROR (MICROPY_CONFIG_ROM_LEVEL_AT_LEAST_EXTRA_FEATURES)
+#endif
+
 // Whether to process __all__ when importing all public symbols from a module.
 #ifndef MICROPY_MODULE___ALL__
 #define MICROPY_MODULE___ALL__ (MICROPY_CONFIG_ROM_LEVEL_AT_LEAST_BASIC_FEATURES)
diff --git a/py/stream.c b/py/stream.c
@@ -108,6 +108,17 @@ const mp_stream_p_t *mp_get_stream_raise(mp_obj_t self_in, int flags) {
     mp_raise_msg(&mp_type_OSError, MP_ERROR_TEXT("stream operation not supported"));
 }
 
+static MP_NORETURN void mp_stream_raise_error(mp_obj_t stream, int error) {
+    #if MICROPY_STREAMS_DELEGATE_ERROR
+    const mp_stream_p_t *stream_p = mp_get_stream(stream);
+    if (stream_p->ioctl != NULL) {
+        int err;
+        stream_p->ioctl(stream, MP_STREAM_RAISE_ERROR, error, &err);
+    }
+    #endif
+    mp_raise_OSError(error);
+}
+
 static mp_obj_t stream_read_generic(size_t n_args, const mp_obj_t *args, byte flags) {
     // What to do if sz < -1?  Python docs don't specify this case.
     // CPython does a readall, but here we silently let negatives through,
@@ -151,7 +162,7 @@ static mp_obj_t stream_read_generic(size_t n_args, const mp_obj_t *args, byte fl
                     }
                     break;
                 }
-                mp_raise_OSError(error);
+                mp_stream_raise_error(args[0], error);
             }
 
             if (out_sz < more_bytes) {
@@ -219,7 +230,7 @@ static mp_obj_t stream_read_generic(size_t n_args, const mp_obj_t *args, byte fl
             // this as EOF.
             return mp_const_none;
         }
-        mp_raise_OSError(error);
+        mp_stream_raise_error(args[0], error);
     } else {
         vstr.len = out_sz;
         if (stream_p->is_text) {
@@ -250,7 +261,7 @@ mp_obj_t mp_stream_write(mp_obj_t self_in, const void *buf, size_t len, byte fla
             // no single byte could be readily written to it."
             return mp_const_none;
         }
-        mp_raise_OSError(error);
+        mp_stream_raise_error(self_in, error);
     } else {
         return MP_OBJ_NEW_SMALL_INT(out_sz);
     }
@@ -327,7 +338,7 @@ static mp_obj_t stream_readall(mp_obj_t self_in) {
                 }
                 break;
             }
-            mp_raise_OSError(error);
+            mp_stream_raise_error(self_in, error);
         }
         if (out_sz == 0) {
             break;
@@ -385,7 +396,7 @@ static mp_obj_t stream_unbuffered_readline(size_t n_args, const mp_obj_t *args)
                     goto done;
                 }
             }
-            mp_raise_OSError(error);
+            mp_stream_raise_error(args[0], error);
         }
         if (out_sz == 0) {
         done:
@@ -435,7 +446,7 @@ mp_obj_t mp_stream_close(mp_obj_t stream) {
     int error;
     mp_uint_t res = stream_p->ioctl(stream, MP_STREAM_CLOSE, 0, &error);
     if (res == MP_STREAM_ERROR) {
-        mp_raise_OSError(error);
+        mp_stream_raise_error(stream, error);
     }
     return mp_const_none;
 }
@@ -463,7 +474,7 @@ static mp_obj_t stream_seek(size_t n_args, const mp_obj_t *args) {
     int error;
     mp_off_t res = mp_stream_seek(args[0], offset, whence, &error);
     if (res == (mp_off_t)-1) {
-        mp_raise_OSError(error);
+        mp_stream_raise_error(args[0], error);
     }
 
     // TODO: Could be uint64
@@ -484,7 +495,7 @@ static mp_obj_t stream_flush(mp_obj_t self) {
     int error;
     mp_uint_t res = stream_p->ioctl(self, MP_STREAM_FLUSH, 0, &error);
     if (res == MP_STREAM_ERROR) {
-        mp_raise_OSError(error);
+        mp_stream_raise_error(self, error);
     }
     return mp_const_none;
 }
@@ -505,7 +516,7 @@ static mp_obj_t stream_ioctl(size_t n_args, const mp_obj_t *args) {
     int error;
     mp_uint_t res = stream_p->ioctl(args[0], mp_obj_get_int(args[1]), val, &error);
     if (res == MP_STREAM_ERROR) {
-        mp_raise_OSError(error);
+        mp_stream_raise_error(args[0], error);
     }
 
     return mp_obj_new_int(res);
diff --git a/py/stream.h b/py/stream.h
@@ -27,23 +27,27 @@
 #ifndef MICROPY_INCLUDED_PY_STREAM_H
 #define MICROPY_INCLUDED_PY_STREAM_H
 
+#include "py/mpconfig.h"
 #include "py/obj.h"
 #include "py/mperrno.h"
 
 #define MP_STREAM_ERROR ((mp_uint_t)-1)
 
 // Stream ioctl request codes
-#define MP_STREAM_FLUSH (1)
-#define MP_STREAM_SEEK  (2)
-#define MP_STREAM_POLL  (3)
-#define MP_STREAM_CLOSE         (4)
-#define MP_STREAM_TIMEOUT       (5)  // Get/set timeout (single op)
-#define MP_STREAM_GET_OPTS      (6)  // Get stream options
-#define MP_STREAM_SET_OPTS      (7)  // Set stream options
-#define MP_STREAM_GET_DATA_OPTS (8)  // Get data/message options
-#define MP_STREAM_SET_DATA_OPTS (9)  // Set data/message options
-#define MP_STREAM_GET_FILENO    (10) // Get fileno of underlying file
-#define MP_STREAM_GET_BUFFER_SIZE (11) // Get preferred buffer size for file
+#define MP_STREAM_FLUSH             (1)
+#define MP_STREAM_SEEK              (2)
+#define MP_STREAM_POLL              (3)
+#define MP_STREAM_CLOSE             (4)
+#define MP_STREAM_TIMEOUT           (5)  // Get/set timeout (single op)
+#define MP_STREAM_GET_OPTS          (6)  // Get stream options
+#define MP_STREAM_SET_OPTS          (7)  // Set stream options
+#define MP_STREAM_GET_DATA_OPTS     (8)  // Get data/message options
+#define MP_STREAM_SET_DATA_OPTS     (9)  // Set data/message options
+#define MP_STREAM_GET_FILENO        (10) // Get fileno of underlying file
+#define MP_STREAM_GET_BUFFER_SIZE   (11) // Get preferred buffer size for file
+#if MICROPY_STREAMS_DELEGATE_ERROR
+#define MP_STREAM_RAISE_ERROR       (12) // Raise an error with detailed error string
+#endif
 
 // These poll ioctl values are compatible with Linux
 #define MP_STREAM_POLL_RD       (0x0001)
@@ -68,8 +72,12 @@ struct mp_stream_seek_t {
 
 // Stream protocol
 typedef struct _mp_stream_p_t {
-    // On error, functions should return MP_STREAM_ERROR and fill in *errcode (values
-    // are implementation-dependent, but will be exposed to user, e.g. via exception).
+    // On error, functions should return MP_STREAM_ERROR and fill in *errcode
+    // (values are are implementation-dependent, but will be exposed to user).
+    // If MICROPY_STREAMS_DELEGATE_ERROR is enabled and ioctl is not null the
+    // stream will receive a MP_STREAM_RAISE_ERROR ioctl request with the arg
+    // containing the errcode, so it may raise a more detailed error. If that
+    // ioctl returns without raising, an OSError with the errcode will raised.
     mp_uint_t (*read)(mp_obj_t obj, void *buf, mp_uint_t size, int *errcode);
     mp_uint_t (*write)(mp_obj_t obj, const void *buf, mp_uint_t size, int *errcode);
     mp_uint_t (*ioctl)(mp_obj_t obj, mp_uint_t request, uintptr_t arg, int *errcode);

Original file line number	Diff line number	Diff line change
`@@ -870,7 +870,14 @@ static mp_uint_t socket_ioctl(mp_obj_t o_in, mp_uint_t request, uintptr_t arg, i`
`870`	`870`	`}`
`871`	`871`	`}`
`872`	`872`	`}`
`873`		`- } else {`
	`873`	`+ }`
	`874`	`+ #if MICROPY_STREAMS_DELEGATE_ERROR`
	`875`	`+ else if (request == MP_STREAM_RAISE_ERROR) {`
	`876`	`+ // Raise error with detailed error string`
	`877`	`+ mbedtls_raise_error((int)arg);`
	`878`	`+ }`
	`879`	`+ #endif`
	`880`	`+ else {`
`874`	`881`	`// Unsupported ioctl.`
`875`	`882`	`*errcode = MP_EINVAL;`
`876`	`883`	`return MP_STREAM_ERROR;`
Original file line number	Diff line number	Diff line change
`@@ -108,6 +108,17 @@ const mp_stream_p_t *mp_get_stream_raise(mp_obj_t self_in, int flags) {`
`108`	`108`	`mp_raise_msg(&mp_type_OSError, MP_ERROR_TEXT("stream operation not supported"));`
`109`	`109`	`}`
`110`	`110`
	`111`	`+static MP_NORETURN void mp_stream_raise_error(mp_obj_t stream, int error) {`
	`112`	`+ #if MICROPY_STREAMS_DELEGATE_ERROR`
	`113`	`+ const mp_stream_p_t *stream_p = mp_get_stream(stream);`
	`114`	`+ if (stream_p->ioctl != NULL) {`
	`115`	`+ int err;`
	`116`	`+ stream_p->ioctl(stream, MP_STREAM_RAISE_ERROR, error, &err);`
	`117`	`+ }`
	`118`	`+ #endif`
	`119`	`+ mp_raise_OSError(error);`
	`120`	`+}`
	`121`	`+`
`111`	`122`	`static mp_obj_t stream_read_generic(size_t n_args, const mp_obj_t *args, byte flags) {`
`112`	`123`	`// What to do if sz < -1? Python docs don't specify this case.`
`113`	`124`	`// CPython does a readall, but here we silently let negatives through,`
`@@ -151,7 +162,7 @@ static mp_obj_t stream_read_generic(size_t n_args, const mp_obj_t *args, byte fl`
`151`	`162`	`}`
`152`	`163`	`break;`
`153`	`164`	`}`
`154`		`- mp_raise_OSError(error);`
	`165`	`+ mp_stream_raise_error(args[0], error);`
`155`	`166`	`}`
`156`	`167`
`157`	`168`	`if (out_sz < more_bytes) {`
`@@ -219,7 +230,7 @@ static mp_obj_t stream_read_generic(size_t n_args, const mp_obj_t *args, byte fl`
`219`	`230`	`// this as EOF.`
`220`	`231`	`return mp_const_none;`
`221`	`232`	`}`
`222`		`- mp_raise_OSError(error);`
	`233`	`+ mp_stream_raise_error(args[0], error);`
`223`	`234`	`} else {`
`224`	`235`	`vstr.len = out_sz;`
`225`	`236`	`if (stream_p->is_text) {`
`@@ -250,7 +261,7 @@ mp_obj_t mp_stream_write(mp_obj_t self_in, const void *buf, size_t len, byte fla`
`250`	`261`	`// no single byte could be readily written to it."`
`251`	`262`	`return mp_const_none;`
`252`	`263`	`}`
`253`		`- mp_raise_OSError(error);`
	`264`	`+ mp_stream_raise_error(self_in, error);`
`254`	`265`	`} else {`
`255`	`266`	`return MP_OBJ_NEW_SMALL_INT(out_sz);`
`256`	`267`	`}`
`@@ -327,7 +338,7 @@ static mp_obj_t stream_readall(mp_obj_t self_in) {`
`327`	`338`	`}`
`328`	`339`	`break;`
`329`	`340`	`}`
`330`		`- mp_raise_OSError(error);`
	`341`	`+ mp_stream_raise_error(self_in, error);`
`331`	`342`	`}`
`332`	`343`	`if (out_sz == 0) {`
`333`	`344`	`break;`
`@@ -385,7 +396,7 @@ static mp_obj_t stream_unbuffered_readline(size_t n_args, const mp_obj_t *args)`
`385`	`396`	`goto done;`
`386`	`397`	`}`
`387`	`398`	`}`
`388`		`- mp_raise_OSError(error);`
	`399`	`+ mp_stream_raise_error(args[0], error);`
`389`	`400`	`}`
`390`	`401`	`if (out_sz == 0) {`
`391`	`402`	`done:`
`@@ -435,7 +446,7 @@ mp_obj_t mp_stream_close(mp_obj_t stream) {`
`435`	`446`	`int error;`
`436`	`447`	`mp_uint_t res = stream_p->ioctl(stream, MP_STREAM_CLOSE, 0, &error);`
`437`	`448`	`if (res == MP_STREAM_ERROR) {`
`438`		`- mp_raise_OSError(error);`
	`449`	`+ mp_stream_raise_error(stream, error);`
`439`	`450`	`}`
`440`	`451`	`return mp_const_none;`
`441`	`452`	`}`
`@@ -463,7 +474,7 @@ static mp_obj_t stream_seek(size_t n_args, const mp_obj_t *args) {`
`463`	`474`	`int error;`
`464`	`475`	`mp_off_t res = mp_stream_seek(args[0], offset, whence, &error);`
`465`	`476`	`if (res == (mp_off_t)-1) {`
`466`		`- mp_raise_OSError(error);`
	`477`	`+ mp_stream_raise_error(args[0], error);`
`467`	`478`	`}`
`468`	`479`
`469`	`480`	`// TODO: Could be uint64`
`@@ -484,7 +495,7 @@ static mp_obj_t stream_flush(mp_obj_t self) {`
`484`	`495`	`int error;`
`485`	`496`	`mp_uint_t res = stream_p->ioctl(self, MP_STREAM_FLUSH, 0, &error);`
`486`	`497`	`if (res == MP_STREAM_ERROR) {`
`487`		`- mp_raise_OSError(error);`
	`498`	`+ mp_stream_raise_error(self, error);`
`488`	`499`	`}`
`489`	`500`	`return mp_const_none;`
`490`	`501`	`}`
`@@ -505,7 +516,7 @@ static mp_obj_t stream_ioctl(size_t n_args, const mp_obj_t *args) {`
`505`	`516`	`int error;`
`506`	`517`	`mp_uint_t res = stream_p->ioctl(args[0], mp_obj_get_int(args[1]), val, &error);`
`507`	`518`	`if (res == MP_STREAM_ERROR) {`
`508`		`- mp_raise_OSError(error);`
	`519`	`+ mp_stream_raise_error(args[0], error);`
`509`	`520`	`}`
`510`	`521`
`511`	`522`	`return mp_obj_new_int(res);`