Skip to content

v2.0.0 - webprogress namespace, errors for failed and truncated downloads, Filename option

Latest
Latest

Choose a tag to compare

View all tags
@github-actions github-actions released this 21 Sep 15:12
v2.0.0
7068f94

MATLAB Versions Tested

downloadFile and uploadFile are now webprogress.download and webprogress.upload, and a download that fails, is interrupted or is cut short raises an error and leaves no file at the target path. Upgrading takes renaming the calls; the arguments are unchanged. See Changed and Removed before upgrading, because a failed download now raises an error where v1.2.1 returned normally.

Added

  • webprogress.download and webprogress.upload accept Filename=NAME, which is shown in the progress title as given and takes precedence over ShowFilename. Use it when the last segment of a download URL is an identifier, or when an uploaded object is known by its path in a storage bucket, such as folder/data.bin (#23).

Changed

  • webprogress.download raises webprogress:download:RequestFailed with the server's status line when the response status is not a 2xx status. In v1.2.1 downloadFile saved the server's error page at the target path and returned that path (#3).
  • webprogress.download saves a file target under the exact name given. In v1.2.1 a target without an extension was given one, from the URL or else from Content-Type, so LICENSE served as text/plain was saved as LICENSE.txt (#14).
  • With a folder as the target, webprogress.download saves the file under the name in the Content-Disposition header, or else under the last segment of the URL path. Only the last component of a Content-Disposition name is used, so a name such as ../outside.txt cannot write outside the folder. A second download into the same folder replaces the file, where it failed with MATLAB:http:CannotOverwriteNoName before (#14).
  • webprogress.toolboxversion returns the version number alone, such as 2.0.0, instead of Version 2.0.0 (#22).
  • The constructor of webprogress.FileTransferProgressMonitor declares its options in an arguments block. It rejects a name that is not an option, such as DisplayMod, which v1.2.1 skipped without notice, and it validates the values. An unambiguous prefix of an option name is accepted, so 'Disp' sets DisplayMode (#8).
  • The FileSizeBytes property of webprogress.FileTransferProgressMonitor can be set only through the constructor, like the other options (#22).

Removed

  • downloadFile and uploadFile no longer exist. Call webprogress.download and webprogress.upload with the same arguments. FileTransferProgressMonitor is now webprogress.FileTransferProgressMonitor (#2).
  • The constructor of webprogress.FileTransferProgressMonitor no longer accepts a scalar struct of options. Pass name-value arguments instead (#8).

Fixed

  • A failed or interrupted download leaves an existing file at the target path unchanged. webprogress.download receives the file in a temporary .part file in the target folder and moves it to the target only after a successful response. The temporary file is deleted when the function exits early, including by an error or Ctrl+C (#14).
  • webprogress.download raises webprogress:download:IncompleteTransfer when the size of the received file differs from the Content-Length of the response. The MATLAB HTTP client returns without an error when the server closes the connection early, so a dropped connection saved a truncated file under the final name. Responses without Content-Length, such as chunked responses, and responses with a Content-Encoding other than identity are not compared (#24).
  • A response with several Content-Length headers of different values raises webprogress:download:InvalidContentLength. A MATLAB release whose HTTP client uses libcurl 8.17.0 or later rejects such a response itself, with MATLAB:webservices:CopyContentToDataStreamError. In both cases no file is saved (#24).
  • webprogress.download raises webprogress:download:FolderNotFound when the folder of the target does not exist, and webprogress:download:NoFilename when a folder target gets no file name from the response or the URL. A response with an empty body saves an empty file (#14).
  • webprogress.upload treats any 2xx status as success. In v1.2.1 uploadFile compared the status with 200 only, so an upload acknowledged with 201 Created or 204 No Content was reported as failed. The error raised for an unsuccessful status has the identifier webprogress:upload:RequestFailed and names the server's status line (#4).
  • Progress is shown for transfers shorter than one second, including the completion message. v1.2.1 set ProgressMonitor.Interval to 1 second, which is the delay before the HTTP stack first calls the monitor, so a 10 MB download that finished sooner printed nothing. Interval is now at most 0.01 seconds and the first update is displayed without waiting for UpdateInterval; later updates are throttled as before (#21, #22).
  • The remaining time is shown only when the transferred fraction supports an estimate. A transfer that had not received its first bytes after ten seconds reported Estimated time remaining: Inf hours; it now shows Estimating remaining time... (#21).
  • When neither the server nor FileSizeBytes gives the size of the transfer, the status line and the completion message report the transferred size alone (#22).
  • Cancelling a transfer closes the progress display and keeps it closed. The byte counts that the HTTP stack reports before it acts on the cancellation opened a new dialog or waitbar (#22).
  • A finished upload is described as an upload. When the server's reply had no body, the completion message read Downloaded 0 MB/0 MB (Inf%) (#5).
  • With ShowFilename, webprogress.download shows the last decoded segment of the URL path, so the title of a signed URL no longer includes the query and its signature, and my%20file.bin is shown as my file.bin. webprogress.upload shows the name of the local file instead of the last segment of the upload URL (#6).
  • The progress passed to uiprogressdlg and the waitbar is limited to the range 0 to 1, and NaN becomes 0. A FileSizeBytes smaller than the transfer raised an error from inside the progress monitor. The percentage in the progress message is not limited, so an incorrect FileSizeBytes remains visible (#7).
  • URLs are validated with matlab.net.URI instead of the undocumented matlab.internal.webservices.urlencode. A URL must have an http or https scheme in lowercase and a host, and an invalid URL raises webprogress:validators:InvalidUrl (#9).
  • webprogress.toolboxversion reports the version of the installed toolbox. In v1.2.1 it reported 1.2.0, because the release updated a second Contents.m that the function does not read (#20).

Documentation

  • webprogress.download and webprogress.upload have help text with one syntax paragraph per output and option. It documents the errors raised, the Figure option and the FileSizeBytes option of download, and that upload raises an error only when it is called without outputs (#11).
  • help webprogress lists the functions of the toolbox below the version header, and the README uses the namespaced function names (#20).

Internal

  • The test suite grows from ToolboxTest to 64 tests in six classes. DownloadTargetTest, ProgressDisplayTest and UploadTest run against a local Python HTTP server in tests/fixtures and are skipped when python3 or a Unix shell is unavailable (#12, #14, #24).
  • The toolbox is packaged from src/webprogress instead of src, so anything that ships in the .mltbx has to live under that folder. webprogress.toolboxdir follows the new layout (#20).
  • webprogresstools.installMatBox picks one .mltbx asset from a MatBox release, and the codespell workflow no longer names a .codespellrc that the repository does not have (#22).
  • The test workflow caches the MATLAB installation and uploads coverage to Codecov (552eea7).
All merged pull requests

What's Changed

  • refactor!: move functions into the webprogress namespace and rename them by @ehennestad in #2
  • fix: raise an error when a download request fails by @ehennestad in #3
  • fix: treat any 2xx upload response as success by @ehennestad in #4
  • fix: describe a finished upload as an upload by @ehennestad in #5
  • fix: show the correct file name in the progress title by @ehennestad in #6
  • fix: keep dialog progress between 0 and 1 by @ehennestad in #7
  • fix: reject unknown options in FileTransferProgressMonitor by @ehennestad in #8
  • fix: validate URLs with the public URI class by @ehennestad in #9
  • docs: add missing help text by @ehennestad in #11
  • test: add tests for download, upload and the progress monitor by @ehennestad in #12
  • fix!: download to a temporary file and save under the exact name by @ehennestad in #14
  • Keep Contents.m in src/webprogress and add its function listing by @ehennestad in #20
  • fix: show progress for short transfers and drop the infinite time estimate by @ehennestad in #21
  • fix: report progress for short transfers and stop cancel reopening the display by @ehennestad in #22
  • feat: add a Filename option to download and upload by @ehennestad in #23
  • fix: raise an error when a download ends before its announced length by @ehennestad in #24

Full Changelog: v1.2.1...v2.0.0

Contributors

ehennestad
Assets 3
Loading