Skip to content

Overview

Hermes Applications and Filesystem Access

Hermes applications are fully sandboxed.
They do not have direct access to Filesystem resources on the host.

However internally, a Hermes application will see a filesystem hierarchy that represents all the files that it may read and/or write.

Hermes presents a filesystem hierarchy to the application which is adapted from the Linux Filesystem Hierarchy Standard V3. Hermes application packages are structured around this standard to maximize consistency.

How Hermes manages and organizes application files is necessary when considering the structure of the Application package itself.

Components to a Hermes Application

Each application consists of two HDF5 files.

  1. The Application package itself.
  2. The Applications persistent re-writable data.

The application itself sees a unified view of these two files. Data is divided between them to make merging those views easy and consistent.

The Full Application Filesystem Hierarchy

Name Type Description Writable Required
/ Root Directory
/tmp Temporary Files stored in memory
/etc Writable settings
/etc/settings.json Hermes Engine settings for this application.
/etc/<module-name>/settings.json Module specific
Runtime Configurable Settings
/srv Data which is served by this system.
/srv/www Files automatically served for this application on HTTP.
/srv/share Data files which are not automatically served but can be shared by all Wasm Modules in the application.
/usr Shareable, read-only data.
/usr/lib Application over-rides for webasm library modules.
/usr/lib/<module-name> Application over-rides for named webasm library module.
/usr/lib/<module-name>/config.json Config to use for the module instead of its bundled config.
/usr/lib/<module-name>/share Overrides for a modules shareable readonly data
/lib Wasm Component Module Library Directory
/lib/<module-name>/metadata.json Modules Metadata
/lib/<module-name>/module.wasm Actual WASM Module
/lib/<module-name>/config.schema.json Modules Fixed Configuration Schema
/lib/<module-name>/config.json Modules Fixed Configuration (Must match the schema)
/lib/<module-name>/settings.schema.json Modules User Settings Schema
/lib/<module-name>/share Modules shareable readonly data
/lib/<module-name>/author.cose Modules Author Signature
/var/ Contains variable data files. (Persistent)
/metadata.json Applications Metadata
/icon.svg Application Icon
/author.cose Application Author Signature
/publisher.cose Application Publisher Signature

Icon Legend

  • - Directory (Persistent)
  • - Directory (Temporary)
  • - General File
  • - Binary File
  • - COSE Certificate
  • - NO
  • - YES

Writable Data

A Hermes application can have access to several writable data source.

  1. Databases - These are not described here and are documented elsewhere.
  2. Temporary file storage - Located in ram and not persisted between invocations of Hermes.
  3. Application writable and persistent storage.

Temporary File Storage

If so configured, Hermes can provide a fixed size re-writable in-memory file system to a Hermes Application. The application will see it at /tmp and it can use it like any normal filesystem. It has a maximum available size, defined by the user. Attempts to write more data than configured will fail. If no temporary storage has been provided to the application it will not see a /tmp directory in its directory hierarchy.

Application writable and persistent storage

The application will also be given a re-writable and persistent file storage. Like the Temporary File Storage it is configured with a maximum size. Attempts by an application to use more storage than configured will fail.

Some data within the Application persistent writable storage is not actually writable by the application directly. This data is used by Hermes to store persistent configuration.
It can be read by the application. This prevents the application from re-writing application settings without the users permission.

From the full Filesystem Hierarchy, the following directories and files are contained in the Application writable and persistent storage.

Name Type Description App Writable Hermes Writable
/ Root Directory
/etc Writable settings
/etc/settings.json Hermes Engine settings for this application.
/etc/<module-name>/settings.json Module specific
Runtime Configurable Settings
/var Contains variable data files. (Persistent)

The application can store any configuration it likes into /etc. Provided it does not modify or delete any settings.json files managed by Hermes itself. The application can read these files at any time.

The application can store any data it requires, with any organization it needs in the /var directory. The only checks performed by hermes on these files are to ensure that the maximum size of the file system is not exceeded.

These files/directories may NEVER appear in a Hermes application package.

The READ ONLY portions of the File System are linked to in the Application Package. During the linking process, file over-rides are processed and cross linked.

This simplifies both the Application logic and Hermes engine as the correct file will appear to exist in the most logical location.

See Loading a Hermes Application

Application Package

Applications in Hermes are packaged and distributed using HDF5 (Hierarchical Data Format Version 5) files. For detailed information see Packaging A Hermes Application.

Application packages consist of the following files.

  1. WASM Library Modules
  2. Configuration Files
  3. Static data files which can be served directly by a Hermes node.
  4. Static data files which can be read by any WASM Library Module within the Application.

HDF5 is a Hierarchial file format. An Application package consists of a number of HDF5 files in the following relationship.

/ (root)/srvConditionally Optional: Data for the service provided by this Application. An Application MUST have at least: - one `/srv/www` file set; or - one `/lib/<module-name>` WASM package./usr/libOPTIONAL: Data overrides for the Application./libConditionally Optional: WASM Component Module Library. An Application MUST have at least: - one `/srv/www` file set; or - one `/lib/<module-name>` WASM package.

HDF5 File

metadata.jsonDefines the application. + Application Name + Version + Description ? Source Repo + License/s + Link to icon in http served files. ? Link to an OpenAPI Document in http served files. + Minimum Resource requirements ? Optimum Resource requirements ? Maximum Resource requirements ? Requested Permissionsicon.svgApplication icon.svg image file.author.coseAuthors identity and Signature over the complete package. May be multiple signatures for multiple authors.publisher.coseOPTIONAL: Publisher identity and Signature over the complete package. May be multiple signatures for multiple publishers./wwwOPTIONAL: Data served on HTTP automatically for the application./shareOPTIONAL: Data sharable by all Modules in the application./<module-name-1>OPTIONAL: Override individual module contents at application level./<module-name-1>WASM Components are individually packaged and signed before inclusion into an application.config.jsonOPTIONAL: Modules runtime config file./shareOverride/Add Data files specific to this Module./shareOPTIONAL: Data files specific to this Module.metadata.jsonDefines the module. + Module Name + Version + Description ? Source Repo + License/smodule.wasmCompiled WASM Component Module.config.schema.jsonOPTIONAL: Schema for the config.json file.config.jsonConditionally Optional: Modules runtime config file. MUST Exist if `config.schema.json` exists.settings.schema.jsonOPTIONAL: Schema for the user option settings.json file.author.coseAuthors signature over the wasm module.Conditionally Optional: Data for the service provided by this Application. An Application MUST have at least: - one `/srv/www` file set; or - one `/lib/<module-name>` WASM package. OPTIONAL: Data overrides for the Application. Conditionally Optional: WASM Component Module Library. An Application MUST have at least: - one `/srv/www` file set; or - one `/lib/<module-name>` WASM package. Defines the application. + Application Name + Version + Description ? Source Repo + License/s + Link to icon in http served files. ? Link to an OpenAPI Document in http served files. + Minimum Resource requirements ? Optimum Resource requirements ? Maximum Resource requirements ? Requested Permissions Application icon.svg image file. Authors identity and Signature over the complete package. May be multiple signatures for multiple authors. OPTIONAL: Publisher identity and Signature over the complete package. May be multiple signatures for multiple publishers. OPTIONAL: Data served on HTTP automatically for the application. OPTIONAL: Data sharable by all Modules in the application. OPTIONAL: Override individual module contents at application level. WASM Components are individually packaged and signed before inclusion into an application. OPTIONAL: Modules runtime config file. Override/Add Data files specific to this Module. OPTIONAL: Data files specific to this Module. Defines the module. + Module Name + Version + Description ? Source Repo + License/s Compiled WASM Component Module. OPTIONAL: Schema for the config.json file. Conditionally Optional: Modules runtime config file. MUST Exist if `config.schema.json` exists. OPTIONAL: Schema for the user option settings.json file. Authors signature over the wasm module.

Application Root

Each application package is an HDF5 file that stores all the static assets, data, and WASM modules. Each application package has associated metadata that is stored in the metadata.json file linked to the root path /.

Application Metadata

Every application includes Metadata which describes:

  • the application itself;
  • important information about the app;
  • where it comes from; and
  • what resources it needs to run.

For detailed information see Application Metadata.

Application Signatures

Applications MUST be signed by their Author/s. They can also OPTIONALLY be signed by one or more publishers. These signatures enable hermes engine to determine if an application is trusted or not.

Except for the party signing the certificate, they are otherwise identical.

For detailed information see Hermes Application Signatures.

Application Static HTTP Assets

Static Assets consist of files that may be published only AS-IS via HTTP by the Application Modules. Application Static Assets are found in the /srv/www path.

These Assets are OPTIONAL, however a valid Hermes application MUST consist of:

  • at least one set of files at /srv/www; or
  • at least one WASM Component Module at /lib/<module-name>

For detailed information see Packaging HTTP Served Files in a Hermes Application.

Application Data

This data is completely optional.

Applications can also include sharable static data. This data is not served automatically, but can be read by any WASM module within the application. Application Data is found in the /src/share path.

For detailed information see Hermes Application Data.

Application Modules

Application Modules are found in the /lib path.

Individual WebAssembly Component Modules are named and stored in a subdirectory with that name.

For example: /lib/greeter is the path to the greeter module.

Modules themselves are pre-packaged and signed and are included into a Hermes Application when it is packaged. Modules may also be sym-linked, for example the same module may be used but configured differently. In this case, it only needs to be included once, and then named links in /lib can reference it.

For example if the greeter module can also function as a goodbye module, it could be linked as so:

/lib/goodbye -> /lib/greeter

This allows modules to be reutilized without wastefully re-including them. The /usr/lib directory allows the runtime contents of a module to be altered by the application. This allows the same code to be used but operate differently because of its configuration.

For detailed information see Hermes WASM Component Module.

Additional Technical Resources

HDF5

CBOR

WASI And WIT

COSE