v0.11.0 - Prefix-scoped bucket cloning, stored KG queries, opening KG instances in the browser

This release lets you clone the part of a bucket that belongs to one dataset, run a stored KG query by its id, and open a KG instance in the browser. It also fixes how query parameters and space restrictions reach the KG. See Removed before upgrading: runDynamicQuery moved to QueriesClient and takes filter values as QueryParameters instead of allRequestParams, and the vendored ebrains.external.filedownload namespace is gone.

Added

• ebrains.bucket.listBucketObjects and ebrains.bucket.createVirtualBucket take Prefix=PREFIX and handle only the objects whose name starts with it, for a dataset whose repository IRI addresses one folder of a shared bucket (<bucket>?prefix=<folder>/). Paths in the virtual bucket keep the prefix (#40).
• QueriesClient.runQueryById runs a stored query (GET /v3/queries/{queryId}/instances). It accepts a bare UUID or a full instance IRI, and RawOutput=true returns the response body as text (#43).
• runDynamicQuery and runQueryById take QueryParameters, a struct with one field per filter parameter that the query specification declares with "parameter": "NAME": QueryParameters=struct(search="hippocampus"). The six names the endpoint binds itself (stage, from, size, returnTotalResults, instanceId, restrictToSpaces) raise EBRAINS:KG_API:ReservedQueryParameter (#43).
• ebrains.kg.viewInstanceOnline opens the page of a KG instance in the browser. The instance is an openminds.Node, a bare UUID or a full instance IRI. View="Search" (default) opens the released version on search.kg.ebrains.eu, View="Preview" the in-progress version, and View="Editor" the KG Editor; the last two need a login. A node that has never been saved (id _:<uuid>) raises EBRAINS:KG:BlankNodeIdentifier. The URLs come from the new constants KgInstanceViewURL, KgInstanceLivePreviewURL and KgInstanceEditorURL and the enumeration ebrains.kg.enum.InstanceView (#42).

Changed

• createVirtualBucket keeps a file that already exists, so cloning a bucket again does not empty files downloaded since the first clone (#40).
• ebrains.bucket.downloadFile no longer writes targetFile + ".part" next to the target; the temporary file is named by tempname. A custom Downloader is called as Downloader(targetFile, url, ...) and must leave the target unchanged when it fails (#41).
• The download and upload behind ebrains.bucket.downloadFile and ebrains.bucket.uploadFile come from http-progressbar-matlab v2.0.0, vendored as ebrains.external.webprogress. Its release notes list the changes in download behaviour (#39).
• The KG methods that act on one instance or query declare identifier (1,1) string, so a string array fails at the argument with an error that names it (#44).
• Passing a type name the KG client does not know, or one that is not expanded, raises EBRAINS:KG_API:UnknownType or EBRAINS:KG_API:UnexpandedTypeName, so a caller can catch either by id (#44).
• The copyright holder is the University of Oslo in LICENSE, Contents.m, codemeta.json and the AuthorCompany of the toolbox, which is also the company shown in the .mltbx metadata and on File Exchange (#44).

Removed

• InstancesClient.runDynamicQuery. Construct an ebrains.kg.api.QueriesClient and call its runDynamicQuery (#43).
• The allRequestParams option of runDynamicQuery. A value passed that way was sent under the name allRequestParams, which matched no filter in the query, so the value was ignored. Pass filter values as QueryParameters=struct(name=value) (#43).
• The namespace ebrains.external.filedownload, with downloadFile and uploadFile. Code that called them directly should call ebrains.external.webprogress.download and ebrains.external.webprogress.upload (#39).

Fixed

• An expired EBRAINS_TOKEN was chosen for every request, so a device flow login with ebrains.authenticate() had no effect. The client credentials client is used for a request only when it holds a valid token or has credentials to fetch one; otherwise the request goes through the device flow client (#38).
• runDynamicQuery sends restrictToSpaces as one query parameter per space. It sent one comma-joined value, which the KG reads as a single space name, so a restriction to several spaces did not apply (#43).
• createVirtualBucket created the folder markers of buckets migrated from the old object storage as empty files. These markers are empty objects with neither a trailing / nor a directory content type; an object whose name is a prefix of another object's name is now created as a folder (#40).
• A malformed EBRAINS_TOKEN made every request fail in the token client constructor with an indexing or missing-field error. The value is now dropped with the warning EBRAINS:IAM:InvalidEnvironmentToken, and the JWT helpers raise EBRAINS:IAM:MalformedToken (#38).
• DeviceFlowTokenClient.instance() constructed a client with missing as its client id when the stored client had been removed with delete instead of reset (#38).

Documentation

• The README has a "Running without a display" section on EBRAINS_TOKEN, EBRAINS_MATLAB_FORCE_CLIENT_CREDENTIALS_OAUTH_FLOW and DisplayMode="Command Window", and a License section (#44).
• CONTRIBUTING.md explains how to run the tests, and CITATION.cff adds GitHub's "Cite this repository" button (#44).

Internal

• tools/tasks/updateVendoredPackages makes the vendored copy of webprogress from a version pin, using matbox.tasks.vendorPackage (#39).
• The token clients name their singleton constant directly instead of through eval, ReturnOptions is a value class, and the unreachable error branches in authenticate and KGCoreApiBaseURL have identifiers (#44).
• New tests cover the bucket prefix, folder markers, re-cloning, object names with a space, $ or ' (#4), the choice of token client, malformed tokens, viewInstanceOnline and QueriesClient. codecov.yml moved into .github (3b0a620), and the reusable live-test workflow is renamed (6183ab0).

All merged pull requests

What's Changed

• fix(iam): three defects in how the token clients hold and choose tokens by @ehennestad in #38
• feat(bucket,external)!: vendor webprogress v2.0.0 in place of filedownload by @ehennestad in #39
• feat(bucket): list and clone the objects below a prefix by @ehennestad in #40
• refactor(bucket): leave the temporary file of a download to webprogress by @ehennestad in #41
• feat(kg): add viewInstanceOnline and the KG instance page URL constants by @ehennestad in #42
• Move query execution to QueriesClient, and fix how query parameters are sent by @ehennestad in #43
• Cleanups from #37 and #4, and name the University of Oslo as copyright holder by @ehennestad in #44

Full Changelog: v0.10.1...v0.11.0