[Bug 2121443] Re: [FFe] Improved API for reporting storage recoverable errors

[Olivier Gayot]

Thanks for asking this question Skia.

The code that I'd like to merge is https://github.com/canonical/subiquity/pull/2070 .
Actually, you will notice it is already merged to subiquity's upstream main branch. But based on the outcome of this FFE, we'll make it part of the ubuntu/questing branch or not.

Should the FFE be approved, the code will be part of the future
25.10/stable subiquity & ubuntu-desktop-bootstrap snaps.

The API that this change is modifying is only consumed by subiquity
itself and ubuntu-desktop-bootstrap. There is no other known consumer.

Also, the API change is only effective when using the associated feature
flag. ubuntu-desktop-bootstrap currently does not enable this feature
flag (although I'm trying to convince them to), so should we need to
roll back, we could technically disable the flag again, rebuild the
snaps and the ISOs.


** Description changed:

  Request
  -------
  
  We want subiquity to ship an improved way to handle recoverable user
  errors in the /storage API.
  
  Typically, the type of error that we are talking about here is an error
  caused by the user requesting something that can't be satisfied, or
  isn't supported such as:
  
-  * disk does not support boot partition
-  * new partition too large
-  * setting the partition name is not implemented.
-  * ...
+  * disk does not support boot partition
+  * new partition too large
+  * setting the partition name is not implemented.
+  * ...
  
  And more rarely, this is caused by the client not using the API
  properly:
  
-  * changing partition format requires a wipe value
+  * changing partition format requires a wipe value
  
  Going forward, the goal is to give the client enough information to:
-  
-  * make the error clearly visible to the user (so they know what they should adjust before retrying)
-  * let the user decide if they want to report a bug
+ 
+  * make the error clearly visible to the user (so they know what they should adjust before retrying)
+  * let the user decide if they want to report a bug
  
  Currently though, what happens by default when using the desktop installer is the following:
-  * subiquity runs into the error
-  * subiquity creates a crash report
-  * subiquity returns HTTP 500 response
-  * the error is not shown to the user (so they don't know what happened)
-  * a "system crash detected" dialog is opened by apport
+  * subiquity runs into the error
+  * subiquity creates a crash report
+  * subiquity returns HTTP 500 response
+  * the error is not shown to the user (so they don't know what happened)
+  * a "system crash detected" dialog is opened by apport
  
  Last cycle, we introduced a feature flag (i.e., --no-report-storage-user-error) which was a step in the right direction. When used, this flag made subiquity:
-  * not produce a crash report when it runs into a recoverable error
-  * return HTTP 422 instead of HTTP 500
+  * not produce a crash report when it runs into a recoverable error
+  * return HTTP 422 instead of HTTP 500
  
  Unfortunately, this wasn't covering enough classes of errors, and not
  providing sufficient information back to the user. So this feature flag
  hasn't been enabled by the desktop installer.
  
  We made a new implementation based on the problems details for HTTP APIs
  RFC.
  
  Why needed
  ----------
  * We want the desktop installer to switch on the feature flag.
-    * This should reduce the number of bug reports we get
-    * This should give users an idea of what to adjust, and therefore increase the number of successful installations.
+    * This should reduce the number of bug reports we get
+    * This should give users an idea of what to adjust, and therefore increase the number of successful installations.
  
  What changed
  ------------
  In the situation described above, the response returned by subiquity now contains:
  
  * An x-error-code field containing the class of error (i.e., storage-invalid-usage, storage-contraint-violated or storage-not-found currently)
  * x-error-title field containing a translated title for the error. E.g., "Invalid use of storage endpoint"
  
  The above is inspired from the problems details for HTTP APIs (RFC 9457)
  
  In addition, more errors have not been converted to user recoverable
  errors, e.g.:
  
-  * edit_partition does not support changing size
+  * edit_partition does not support changing size
+ 
+ Additional information
+ ----------------------
+ Code to merge for questing: https://github.com/canonical/subiquity/pull/2070
+ The updated code will be part of the future 25.10/stable snaps for subiquity & ubuntu-desktop-bootstrap should the FFE be approved.

-- 
You received this bug notification because you are a member of Ubuntu
Foundations Bugs, which is subscribed to subiquity in Ubuntu.
https://bugs.launchpad.net/bugs/2121443

Title:
  [FFe] Improved API for reporting storage recoverable errors

Status in subiquity:
  New
Status in subiquity package in Ubuntu:
  New

Bug description:
  Request
  -------

  We want subiquity to ship an improved way to handle recoverable user
  errors in the /storage API.

  Typically, the type of error that we are talking about here is an
  error caused by the user requesting something that can't be satisfied,
  or isn't supported such as:

   * disk does not support boot partition
   * new partition too large
   * setting the partition name is not implemented.
   * ...

  And more rarely, this is caused by the client not using the API
  properly:

   * changing partition format requires a wipe value

  Going forward, the goal is to give the client enough information to:

   * make the error clearly visible to the user (so they know what they should adjust before retrying)
   * let the user decide if they want to report a bug

  Currently though, what happens by default when using the desktop installer is the following:
   * subiquity runs into the error
   * subiquity creates a crash report
   * subiquity returns HTTP 500 response
   * the error is not shown to the user (so they don't know what happened)
   * a "system crash detected" dialog is opened by apport

  Last cycle, we introduced a feature flag (i.e., --no-report-storage-user-error) which was a step in the right direction. When used, this flag made subiquity:
   * not produce a crash report when it runs into a recoverable error
   * return HTTP 422 instead of HTTP 500

  Unfortunately, this wasn't covering enough classes of errors, and not
  providing sufficient information back to the user. So this feature
  flag hasn't been enabled by the desktop installer.

  We made a new implementation based on the problems details for HTTP
  APIs RFC.

  Why needed
  ----------
  * We want the desktop installer to switch on the feature flag.
     * This should reduce the number of bug reports we get
     * This should give users an idea of what to adjust, and therefore increase the number of successful installations.

  What changed
  ------------
  In the situation described above, the response returned by subiquity now contains:

  * An x-error-code field containing the class of error (i.e., storage-invalid-usage, storage-contraint-violated or storage-not-found currently)
  * x-error-title field containing a translated title for the error. E.g., "Invalid use of storage endpoint"

  The above is inspired from the problems details for HTTP APIs (RFC
  9457)

  In addition, more errors have not been converted to user recoverable
  errors, e.g.:

   * edit_partition does not support changing size

  Additional information
  ----------------------
  Code to merge for questing: https://github.com/canonical/subiquity/pull/2070
  The updated code will be part of the future 25.10/stable snaps for subiquity & ubuntu-desktop-bootstrap should the FFE be approved.

To manage notifications about this bug go to:
https://bugs.launchpad.net/subiquity/+bug/2121443/+subscriptions