8000 [breaking] Refactor `DownloadProgress` gRPC message: more clear field meaning. by cmaglie · Pull Request #1875 · arduino/arduino-cli · GitHub
[go: up one dir, main page]
Skip to content

[breaking] Refactor DownloadProgress gRPC message: more clear field meaning. #1875

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Oct 5, 2022
Merged

[breaking] Refactor DownloadProgress gRPC message: more clear field meaning. #1875

Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
31722ce
Refactored DownloadProgress protocol
cmaglie Sep 22, 2022
350e90f
Updated integration tests
cmaglie Sep 22, 2022
deae0a2
Do not create overly verbose errors
cmaglie Sep 22, 2022
13b3f85
Updated docs
cmaglie Sep 13, 2022
c28cfd3
Update rpc/cc/arduino/cli/commands/v1/commands.proto
cmaglie Oct 4, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Updated docs
  • Loading branch information
@cmaglie
cmaglie committed Sep 22, 2022
commit 13b3f8541e3c85810ab3a1f501f9b135449bbb5c
85 changes: 63 additions & 22 deletions docs/UPGRADING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,55 +58,96 @@ replacement.

### Breaking changes in UpdateIndex API (both gRPC and go-lang)

The gRPC message `cc.arduino.cli.commands.v1.UpdateIndexResponse` has been changed from:
The gRPC message `cc.arduino.cli.commands.v1.DownloadProgress` has been changed from:

```
message UpdateIndexResponse {
// Progress of the platforms index download.
DownloadProgress download_progress = 1;
message DownloadProgress {
// URL of the download.
string url = 1;
// The file being downloaded.
string file = 2;
// Total size of the file being downloaded.
int64 total_size = 3;
// Size of the downloaded portion of the file.
int64 downloaded = 4;
// Whether the download is complete.
bool completed = 5;
}
```

to

```
message UpdateIndexResponse {
message DownloadProgress {
oneof message {
// Progress of the platforms index download.
DownloadProgress download_progress = 1;
// Report of the index update downloads.
DownloadResult download_result = 2;
DownloadProgressStart start = 1;
DownloadProgressUpdate update = 2;
DownloadProgressEnd end = 3;
}
}

message DownloadResult {
// Index URL.
message DownloadProgressStart {
// URL of the download.
string url = 1;
// Download result: true if successful, false if an error occurred.
bool successful = 2;
// Download error details.
string error = 3;
// The label to display on the progress bar.
string label = 2;
}

message DownloadProgressUpdate {
// Size of the downloaded portion of the file.
int64 downloaded = 1;
// Total size of the file being downloaded.
int64 total_size = 2;
}

message DownloadProgressEnd {
// True if the download is successful
bool success = 1;
// Info or error message, depending on the value of 'success'. Some examples:
// "File xxx already downloaded" or "Connection timeout"
string message = 2;
}
```

The new message format allows a better handling of the progress update reports on downloads. Every download now will
report a sequence of message as follows:

```
DownloadProgressStart{url="https://...", label="Downloading package index..."}
DownloadProgressUpdate{downloaded=0, total_size=103928}
DownloadProgressUpdate{downloaded=29380, total_size=103928}
DownloadProgressUpdate{downloaded=69540, total_size=103928}
DownloadProgressEnd{success=true, message=""}
```

or if an error occurs:

```
DownloadProgressStart{url="https://...", label="Downloading package index..."}
DownloadProgressUpdate{downloaded=0, total_size=103928}
DownloadProgressEnd{success=false, message="Server closed connection"}
```

or if the file is already cached:

```
DownloadProgressStart{url="https://...", label="Downloading package index..."}
DownloadProgressEnd{success=true, message="Index already downloaded"}
```

even if not strictly a breaking change it's worth noting that the detailed error message is now streamed in the
response. About the go-lang API the following functions in `github.com/arduino/arduino-cli/commands`:
About the go-lang API the following functions in `github.com/arduino/arduino-cli/commands`:

```go
func UpdateIndex(ctx context.Context, req *rpc.UpdateIndexRequest, downloadCB rpc.DownloadProgressCB) (*rpc.UpdateIndexResponse, error) { ... }
func UpdateCoreLibrariesIndex(ctx context.Context, req *rpc.UpdateCoreLibrariesIndexRequest, downloadCB rpc.DownloadProgressCB) error { ... }
```

have changed their signature to:

```go
func UpdateIndex(ctx context.Context, req *rpc.UpdateIndexRequest, downloadCB rpc.DownloadProgressCB, downloadResultCB rpc.DownloadResultCB) error { ... }
func UpdateCoreLibrariesIndex(ctx context.Context, req *rpc.UpdateCoreLibrariesIndexRequest, downloadCB rpc.DownloadProgressCB, downloadResultCB rpc.DownloadResultCB) error { ... }
```

`UpdateIndex` do not return anymore the latest `UpdateIndexResponse` (it was always empty). Both `UpdateIndex` and
`UpdateCoreLibrariesIndex` now accepts an `rpc.DownloadResultCB` to get download results, you can pass an empty callback
if you're not interested in the error details.
`UpdateIndex` do not return anymore the latest `UpdateIndexResponse` (beacuse it was always empty).

## 0.27.0

Expand Down
0