wvb 0.0.1

TBD
Documentation

webview-bundle

Webview Bundle is offline-first web resources delivery system for webview mounted frameworks/platforms. ( e.g. Electron, Tauri, Android and iOS are planned)

[!NOTE] This project is under development.

Webview Bundle Format (.wvb)

Header

  • Magic Number (8 bytes)
    • Big endian format. Value : 0xf09f8c90 / 0xf09f8e81
    • Represents "🌐🎁" as utf8 encoding.
  • Version (1 bytes)
    • Version field for this webview bundle format.
    • Available versions:
      • version1: 0x01
  • Index Size (4 bytes)
    • 4 bytes unsigned big endian value (u32)
    • Indicates the size of the Index field to be read next.
  • Header checksum (4 bytes)
    • Checksum verifies that the full header data has been decoded correctly.
    • The checksum is the result of xxHash-32 algorithm digesting the header data as input.

Index

  • Index
    • This field has dynamic bytes size which is determined by the value of the Index Size field, and value is a big endian format.
    • Format of index should be HashMap formatted with binary encoded:
      • Key is a path for this file.
      • Value contains offset, length for reading contents from the data field.
      • Value can contain http headers which will be included in the response.
  • Index checksum (4 bytes)
    • Checksum verifies that the full index data has been decoded correctly.
    • The checksum is the result of xxHash-32 algorithm digesting the encoded index data as input.

Data

  • Data
    • This field has dynamic bytes size which can be determined each file offset and length from Index.
    • The content of data is compressed with lz4 block format.
    • The last 4 bytes are the checksum which is the result of xxHash-32 algorithm digesting the compressed data as input.

Source

A Source is a structure that stores multiple webview bundles locally, composed of a combination of directories and a manifest.json file.

The directory structure is as follows:

{dir}
|- {bundle_name}
|  |- {bundle_name}_{version}.wvb
|- app
|  |- app_1.0.0.wvb
|  |- app_1.1.0.wvb
|- manifest.json

The manifest.json records version information and other metadata for the bundles located in the directory, as well as the current version of each bundle.

Below is the manifest v1 schema:

{
  "manifestVersion": 1,
  "entries": {
    "<bundle_name>": {
      "versions": {
        "<version>": {
          "etag": "(optional)",
          "integrity": "(optional)",
          "signature": "(optional)",
          "last_modified": "(optional)"
        },
        "currentVersion": "<version>"
      }
    },
    "app": {
      "versions": {
        "1.0.0": {}
      },
      "currentVersion": "1.0.0"
    }
  }
}

Directories can be separated into two types within the application:

  • builtin: A bundle Source that is shipped together with the application distribution. It is used as a fallback when the latest bundles cannot be downloaded from the remote, such as during the application's first launch. It is generally treated as read-only.
  • remote: Contains the latest bundles downloaded from the remote. If a bundle with the same name exists in both builtin and remote, the remote version takes priority.

Remote HTTP Spec

List bundles (GET /bundles)

This returns a list of bundles.

Remote bundles must be version-specified. Therefore, bundles with un-deployed versions should be excluded from the response.

GET /bundles
Host: wvb.example.com
Accept: application/json

### Response
HTTP 200 OK
Content-Type: application/json

[{ "name": "bundle1", "version": "1.0.0" }]

Get the current bundle info (HEAD /bundles/{name})

Get a bundle metadata with the specified name.

Bundle metadata includes the following metadata in response headers:

  • webview-bundle-name : The name of this bundle.
  • webview-bundle-version : Currently deployed version of this bundle.
  • webview-bundle-integrity : (Optional) Integrity of this bundle which can be used for verification.
  • webview-bundle-signature : (Optional) Sinature of this bundle which can be used for verification.
HEAD /bundles/{name}
Host: wvb.example.com

### Response
HTTP 200 OK
Content-Type: application/webview-bundle
Webview-Bundle-Name: bundle_name_1
Webview-Bundle-Version: 1.0.0
Webview-Bundle-Integrity: ...
Webview-Bundle-Signature: ...

Exceptions

If the bundle does not exist, or the bundle is not deployed, the server will return a 404 Not Found response.

HEAD /bundles/{name}
Host: wvb.example.com

### Response
HTTP 404 Not Found

Download the current bundle (GET /bundles/{name})

Download the current bundle with the specified name.

Bundle metadata includes the following metadata in response headers:

  • webview-bundle-name : The name of this bundle.
  • webview-bundle-version : Currently deployed version of this bundle.
  • webview-bundle-integrity : (Optional) Integrity of this bundle which can be used for verification.
  • webview-bundle-signature : (Optional) Sinature of this bundle which can be used for verification.
GET /bundles/{name}
Host: wvb.example.com

### Response
HTTP 200 OK
Content-Type: application/webview-bundle
Webview-Bundle-Name: bundle_name_1
Webview-Bundle-Version: 1.0.0
Webview-Bundle-Integrity: ...
Webview-Bundle-Signature: ...

(binary data)

Exceptions

If the bundle does not exist, or the bundle is not deployed, the server will return a 404 Not Found response.

HEAD /bundles/{name}
Host: wvb.example.com

### Response
HTTP 404 Not Found

Download a specific version of the bundle (GET /bundles/{name}/{version})

Get a specific version of the bundle with the specified name and version.

In the enterprise cases, you may want to prevent downloading specific versions. You can enable this feature by using the allowOtherVersions option.

GET /bundles/{name}/{version}
Host: wvb.example.com

### Response
HTTP 200 OK
Content-Type: application/webview-bundle
Webview-Bundle-Name: bundle_name_1
Webview-Bundle-Version: 1.0.0
Webview-Bundle-Integrity: ...
Webview-Bundle-Signature: ...

Exceptions

If the bundle does not exist, or the bundle is not deployed, the server will return a 404 Not Found response.

GET /bundles/{name}/{version}
Host: wvb.example.com

### Response
HTTP 404 Not Found

If the allowOtherVersions option is not enabled, the server will return a 403 Forbidden response.

GET /bundles/{name}/{version}
Host: wvb.example.com

### Response
HTTP 403 Forbidden