@@ -58,55 +58,96 @@ replacement.
5858
5959### Breaking changes in UpdateIndex API (both gRPC and go-lang)
6060
61- The gRPC message ` cc.arduino.cli.commands.v1.UpdateIndexResponse ` has been changed from:
61+ The gRPC message ` cc.arduino.cli.commands.v1.DownloadProgress ` has been changed from:
6262
6363```
64- message UpdateIndexResponse {
65- // Progress of the platforms index download.
66- DownloadProgress download_progress = 1;
64+ message DownloadProgress {
65+ // URL of the download.
66+ string url = 1;
67+ // The file being downloaded.
68+ string file = 2;
69+ // Total size of the file being downloaded.
70+ int64 total_size = 3;
71+ // Size of the downloaded portion of the file.
72+ int64 downloaded = 4;
73+ // Whether the download is complete.
74+ bool completed = 5;
6775}
6876```
6977
7078to
7179
7280```
73- message UpdateIndexResponse {
81+ message DownloadProgress {
7482 oneof message {
75- // Progress of the platforms index download.
76- DownloadProgress download_progress = 1;
77- // Report of the index update downloads.
78- DownloadResult download_result = 2;
83+ DownloadProgressStart start = 1;
84+ DownloadProgressUpdate update = 2;
85+ DownloadProgressEnd end = 3;
7986 }
8087}
8188
82- message DownloadResult {
83- // Index URL.
89+ message DownloadProgressStart {
90+ // URL of the download .
8491 string url = 1;
85- // Download result: true if successful, false if an error occurred.
86- bool successful = 2;
87- // Download error details.
88- string error = 3;
92+ // The label to display on the progress bar.
93+ string label = 2;
8994}
95+
96+ message DownloadProgressUpdate {
97+ // Size of the downloaded portion of the file.
98+ int64 downloaded = 1;
99+ // Total size of the file being downloaded.
100+ int64 total_size = 2;
101+ }
102+
103+ message DownloadProgressEnd {
104+ // True if the download is successful
105+ bool success = 1;
106+ // Info or error message, depending on the value of 'success'. Some examples:
107+ // "File xxx already downloaded" or "Connection timeout"
108+ string message = 2;
109+ }
110+ ```
111+ 112+ The new message format allows a better handling of the progress update reports on downloads. Every download now will
113+ report a sequence of message as follows:
114+ 115+ ```
116+ DownloadProgressStart{url="https://...", label="Downloading package index..."}
117+ DownloadProgressUpdate{downloaded=0, total_size=103928}
118+ DownloadProgressUpdate{downloaded=29380, total_size=103928}
119+ DownloadProgressUpdate{downloaded=69540, total_size=103928}
120+ DownloadProgressEnd{success=true, message=""}
121+ ```
122+ 123+ or if an error occurs:
124+ 125+ ```
126+ DownloadProgressStart{url="https://...", label="Downloading package index..."}
127+ DownloadProgressUpdate{downloaded=0, total_size=103928}
128+ DownloadProgressEnd{success=false, message="Server closed connection"}
129+ ```
130+ 131+ or if the file is already cached:
132+ 133+ ```
134+ DownloadProgressStart{url="https://...", label="Downloading package index..."}
135+ DownloadProgressEnd{success=true, message="Index already downloaded"}
90136```
91137
92- even if not strictly a breaking change it's worth noting that the detailed error message is now streamed in the
93- response. About the go-lang API the following functions in ` github.com/arduino/arduino-cli/commands ` :
138+ About the go-lang API the following functions in ` github.com/arduino/arduino-cli/commands ` :
94139
95140``` go
96141func UpdateIndex (ctx context .Context , req *rpc .UpdateIndexRequest , downloadCB rpc .DownloadProgressCB ) (*rpc .UpdateIndexResponse , error ) { ... }
97- func UpdateCoreLibrariesIndex (ctx context .Context , req *rpc .UpdateCoreLibrariesIndexRequest , downloadCB rpc .DownloadProgressCB ) error { ... }
98142```
99143
100144have changed their signature to:
101145
102146``` go
103147func UpdateIndex (ctx context .Context , req *rpc .UpdateIndexRequest , downloadCB rpc .DownloadProgressCB , downloadResultCB rpc .DownloadResultCB ) error { ... }
104- func UpdateCoreLibrariesIndex (ctx context .Context , req *rpc .UpdateCoreLibrariesIndexRequest , downloadCB rpc .DownloadProgressCB , downloadResultCB rpc .DownloadResultCB ) error { ... }
105148```
106149
107- ` UpdateIndex ` do not return anymore the latest ` UpdateIndexResponse ` (it was always empty). Both ` UpdateIndex ` and
108- ` UpdateCoreLibrariesIndex ` now accepts an ` rpc.DownloadResultCB ` to get download results, you can pass an empty callback
109- if you're not interested in the error details.
150+ ` UpdateIndex ` do not return anymore the latest ` UpdateIndexResponse ` (beacuse it was always empty).
110151
111152## 0.27.0
112153
0 commit comments