Skip to content
This repository has been archived by the owner on Sep 7, 2022. It is now read-only.

Latest commit

 

History

History
98 lines (73 loc) · 5.47 KB

file_protocols.md

File metadata and controls

98 lines (73 loc) · 5.47 KB
Raw

File-backed data sources, which include precomputed, zarr, n5, and nifti, support the following URL protocols for accessing file data:

  • http:// and https://: unathenticated HTTP access via normal GET requests.

    Neuroglancer supports interactive completion of data source URLs if the web server provides HTML directory listings.

    Note that because of mixed content blocking in Chrome and Firefox, if the Neuroglancer client itself is served from an https:// URL (e.g. https://neuroglancer-demo.appspot.com), Neuroglancer cannot access data sources using http:// URLs, only https://) URLs are allowed. However, data sources served from http://127.0.0.1[:PORT] (on Chrome and Firefox) and http://localhost[:PORT] (on Chrome) are allowed by exceptions to the normal mixed content blocking.

    If the Neuroglancer client is served from an http:// URL, data sources served from both http:// and https:// URLs are supported.

    If the data source is served from a different origin than the Neuroglancer client itself, then the server hosting the data must allow cross-origin requests. The web server must be configured to send an appropriate Access-Control-Allow-Origin header.

  • gs://BUCKET/PATH: access to Google Cloud Storage (GCS) buckets

    • When not using the Python integration, Neuroglancer can only access buckets that allow public read access and do not require requester pays.

      Specifically, the bucket must grant storage.objects.get permission to allUsers, which you can enable using these instructions.

      If storage.objects.list permission is also granted to allUsers, Neuroglancer supports interactive completion of data source URLs.

      To access non-public buckets, you can use an ngauth server, described below.

      Another method for keeping data private while still allowing Neuroglancer to access it without the need for an ngauth server is to include a long, random string as a suffix of the bucket name, such that the bucket name itself serves as the secret key.

    • When using the Python integration, Neuroglancer can access non-public buckets without ngauth, using Application Default Credentials provided by the Neuroglancer Python library.

    The gs:// protocol uses the Google Cloud Storage JSON API, which never receives stale data even if caching is enabled, and does not require that you configure a CORS policy. To take advantage of HTTP caching (which may provide slightly better performance), you can use the S3-compatible XML API using the gs+xml:// protocol, as described below.

  • gs+xml://BUCKET/PATH: access to Google Cloud Storage (GCS) buckets using the S3-compatible XML API.

    Differs from gs:// in that cached (and possibly stale) data may be received if caching is enabled. You must configure a CORS policy, such as the following:

    [{"maxAgeSeconds": 3600, "method": ["GET"], "origin": ["*"], "responseHeader": ["Content-Type", "Range"]}]

  • gs+ngauth+http://NGAUTH_SERVER/BUCKET/PATH and gs+ngauth+https://NGAUTH_SERVER/BUCKET/PATH: access to non-public Google Cloud Storage (GCS) buckets via an ngauth server.

    This protocol uses the the Google Cloud Storage JSON API. To use the XML API instead, you can use gs+xml+ngauth+http:// or gs+xml+ngauth+https://.

    The first time you use a given ngauth server, a status message at the bottom of the browser window will prompt you to log in. Once you log in with your Google account using Google Sign In, you can access buckets that both your user account and the ngauth server has permission to access.

    Refer to the ngauth server documentation for details.

    When using the Python integration, the NGAUTH_SERVER is ignored and credentials are provided by the Neuroglancer Python library instead, as for the gs:// protocol.

  • gs+ngauth+http://NGAUTH_SERVER/BUCKET/PATH and gs+ngauth+https://NGAUTH_SERVER/BUCKET/PATH: access to non-public Google Cloud Storage (GCS) buckets via an ngauth server using the S3-compatible XML API.

  • s3://BUCKET/PATH: access to public Amazon Simple Storage Service (S3) buckets.

    Only buckets that allow public read access and do not require requester pays are supported.

    Additionally, you must configure a suitable CORS configuration.