@@ -6,55 +6,96 @@ Here you can find a list of migration guides to handle breaking changes between
66
77### Breaking changes in UpdateIndex API (both gRPC and go-lang)
88
9- The gRPC message ` cc.arduino.cli.commands.v1.UpdateIndexResponse ` has been changed from:
9+ The gRPC message ` cc.arduino.cli.commands.v1.DownloadProgress ` has been changed from:
1010
1111```
12- message UpdateIndexResponse {
13- // Progress of the platforms index download.
14- DownloadProgress download_progress = 1;
12+ message DownloadProgress {
13+ // URL of the download.
14+ string url = 1;
15+ // The file being downloaded.
16+ string file = 2;
17+ // Total size of the file being downloaded.
18+ int64 total_size = 3;
19+ // Size of the downloaded portion of the file.
20+ int64 downloaded = 4;
21+ // Whether the download is complete.
22+ bool completed = 5;
1523}
1624```
1725
1826to
1927
2028```
21- message UpdateIndexResponse {
29+ message DownloadProgress {
2230 oneof message {
23- // Progress of the platforms index download.
24- DownloadProgress download_progress = 1;
25- // Report of the index update downloads.
26- DownloadResult download_result = 2;
31+ DownloadProgressStart start = 1;
32+ DownloadProgressUpdate update = 2;
33+ DownloadProgressEnd end = 3;
2734 }
2835}
2936
30- message DownloadResult {
31- // Index URL.
37+ message DownloadProgressStart {
38+ // URL of the download .
3239 string url = 1;
33- // Download result: true if successful, false if an error occurred.
34- bool successful = 2;
35- // Download error details.
36- string error = 3;
40+ // The label to display on the progress bar.
41+ string label = 2;
3742}
43+
44+ message DownloadProgressUpdate {
45+ // Size of the downloaded portion of the file.
46+ int64 downloaded = 1;
47+ // Total size of the file being downloaded.
48+ int64 total_size = 2;
49+ }
50+
51+ message DownloadProgressEnd {
52+ // True if the download is successful
53+ bool success = 1;
54+ // Info or error message, depending on the value of 'success'. Some examples:
55+ // "File xxx already downloaded" or "Connection timeout"
56+ string message = 2;
57+ }
58+ ```
59+ 60+ The new message format allows a better handling of the progress update reports on downloads.
61+ Every download now will report a sequence of message as follows:
62+ 63+ ```
64+ DownloadProgressStart{url="https://...", label="Downloading package index..."}
65+ DownloadProgressUpdate{downloaded=0, total_size=103928}
66+ DownloadProgressUpdate{downloaded=29380, total_size=103928}
67+ DownloadProgressUpdate{downloaded=69540, total_size=103928}
68+ DownloadProgressEnd{success=true, message=""}
69+ ```
70+ 71+ or if an error occurs:
72+ 73+ ```
74+ DownloadProgressStart{url="https://...", label="Downloading package index..."}
75+ DownloadProgressUpdate{downloaded=0, total_size=103928}
76+ DownloadProgressEnd{success=false, message="Server closed connection"}
77+ ```
78+ 79+ or if the file is already cached:
80+ 81+ ```
82+ DownloadProgressStart{url="https://...", label="Downloading package index..."}
83+ DownloadProgressEnd{success=true, message="Index already downloaded"}
3884```
3985
40- even if not strictly a breaking change it's worth noting that the detailed error message is now streamed in the
41- response. About the go-lang API the following functions in ` github.com/arduino/arduino-cli/commands ` :
86+ About the go-lang API the following functions in ` github.com/arduino/arduino-cli/commands ` :
4287
4388``` go
4489func UpdateIndex (ctx context .Context , req *rpc .UpdateIndexRequest , downloadCB rpc .DownloadProgressCB ) (*rpc .UpdateIndexResponse , error ) { ... }
45- func UpdateCoreLibrariesIndex (ctx context .Context , req *rpc .UpdateCoreLibrariesIndexRequest , downloadCB rpc .DownloadProgressCB ) error { ... }
4690```
4791
4892have changed their signature to:
4993
5094``` go
5195func UpdateIndex (ctx context .Context , req *rpc .UpdateIndexRequest , downloadCB rpc .DownloadProgressCB , downloadResultCB rpc .DownloadResultCB ) error { ... }
52- func UpdateCoreLibrariesIndex (ctx context .Context , req *rpc .UpdateCoreLibrariesIndexRequest , downloadCB rpc .DownloadProgressCB , downloadResultCB rpc .DownloadResultCB ) error { ... }
5396```
5497
55- ` UpdateIndex ` do not return anymore the latest ` UpdateIndexResponse ` (it was always empty). Both ` UpdateIndex ` and
56- ` UpdateCoreLibrariesIndex ` now accepts an ` rpc.DownloadResultCB ` to get download results, you can pass an empty callback
57- if you're not interested in the error details.
98+ ` UpdateIndex ` do not return anymore the latest ` UpdateIndexResponse ` (beacuse it was always empty).
5899
59100## 0.27.0
60101
0 commit comments