Capsium

Capsium: Common architecture for portable secure information interchange and unified management.

Capsium is designed to facilitate the creation, management and deployment of content packages with ease.

This gem provides a structured way to handle content, data, and metadata for various applications.

Test it out!

$ capsium reactor serve https://github.com/capsiums/cap-story/releases/download/v0.9.0/story_of_claire-0.9.0.cap

Or:

$ wget https://github.com/capsiums/cap-story/releases/download/v0.9.0/story_of_claire-0.9.0.cap
$ capsium reactor serve story_of_claire-0.9.0.cap
$ open http://localhost:8864
# => Read the story!#

Building the mn-samples-iso cap package

Download the mn-samples-iso built site: mn-samples-iso-Linux.

Then run these commands:

$ unzip mn-samples-iso-Linux.zip
$ cd mn-samples-iso-Linux
$ mkdir content
$ mv index.html documents.xml documents content
$ echo '{"name": "mn-samples-iso","version":"0.1.0"}' > metadata.json
$ cd ..
$ bundle exec capsium package pack -f mn-samples-iso-Linux
Package created: mn-samples-iso-0.1.0.cap
$ bundle exec capsium reactor serve mn-samples-iso-0.1.0.cap
Starting server on http://localhost:8864
[2024-06-05 14:56:41] INFO  WEBrick::HTTPServer#start: pid=8234 port=8864
...

Installation

To install the Capsium gem, add it to your Gemfile:

gem 'capsium'

Then, run the following command to install it:

bundle install

Alternatively, you can install the gem directly using:

gem install capsium

What is a Capsium package?

A Capsium package is a structured collection of content, data, metadata, and routing information. It is designed to encapsulate all resources needed for a particular application or service in a well-organized format. A package typically includes:

Content: Static files like HTML, CSS, and JavaScript.
Data: Structured data files, such as YAML or JSON.
Metadata: Descriptive information about the package, such as its name, version, and dependencies.
Routes: Mapping of URLs to content or data endpoints.
Storage: Definitions for datasets and their sources, formats, and schemas.

What is a Capsium reactor?

A Capsium reactor is a runtime environment that serves Capsium packages. It reads the package configuration and starts a server that can handle HTTP requests according to the routes defined in the package. The reactor ensures that the content and data within the package are served correctly, allowing for easy integration and deployment of packaged applications.

CLI: Package

To pack a package, you need to define the content, data, metadata, routes, and storage configurations. Once defined, you can use the Capsium command-line interface (CLI) to create and manage your packages.

Capsium provides a CLI to help you pack and manage your packages. Here are some common commands:

# TODO: Create a new package
# Full command
capsium package new my_package
# Shorthand
capsium package my_package

# TODO: Add content to the package
capsium package add content example.html example.css example.js

# TODO: Add data to the package
capsium package add data animals.yaml

# TODO: Add metadata to the package
capsium package add metadata name=sample_package version=0.1.0

# TODO: Define routes for the package
capsium package add route /=example.html /index=index.html /api/v1/data/animals={type:dataset,name:animals}

# TODO: Define storage for the package
capsium package add storage datasets=[{name:animals,source:data/animals.yaml,format:yaml,schema:data/animals_schema.yaml}]

Packing a package

To pack an existing Capsium package directory, use the following command:

capsium package pack [--force/-f] path-to-package

This command will pack your package into a single file with the filename:

{package-name}-{package-version}.cap
where the name and version both come from {package-path}/metadata.json

Example 1. Sample pack command

capsium package pack -f spec/fixtures/bare_package

Example 2. Sample unpack command

capsium package unpack bare_package-0.1.0.cap my_bare_package

CLI: Reactor

Starting a reactor on your package

To start a Capsium reactor on your package, use the following command:

capsium reactor serve my_package.cap

Programmatically managing packages

You can also create, load, and use packages programmatically within your Ruby application.

Creating packages

require 'capsium'

package = Capsium::Package.new(
  name: 'sample_package',
  version: '0.1.0',
  content: {
    'example.html' => 'text/html',
    'example.css' => 'text/css',
    'example.js' => 'application/javascript'
  },
  data: {
    'animals.yaml' => {
      'animals' => [
        { 'name' => 'Lion', 'type' => 'Mammal', 'habitat' => 'Savannah' },
        { 'name' => 'Eagle', 'type' => 'Bird', 'habitat' => 'Mountains' },
        { 'name' => 'Shark', 'type' => 'Fish', 'habitat' => 'Ocean' }
      ]
    }
  },
  metadata: {
    'name' => 'sample_package',
    'version' => '0.1.0',
    'dependencies' => []
  },
  routes: {
    '/' => 'example.html',
    '/index' => 'index.html',
    '/index.html' => 'index.html',
    '/example.css' => 'example.css',
    '/example.js' => 'example.js',
    '/api/v1/data/animals' => { 'type' => 'dataset', 'name' => 'animals' }
  },
  storage: {
    'datasets' => [
      {
        'name' => 'animals',
        'source' => 'data/animals.yaml',
        'format' => 'yaml',
        'schema' => 'data/animals_schema.yaml'
      }
    ]
  }
)

# Save the package to a file
File.write('my_package.json', package.to_json(pretty: true))

Loading packages

To load an existing package from a JSON file, you can use the Capsium::Package.new(path) method:

require 'capsium'

# Read the package file or folder
package = Capsium::Package.new(path)

# Inspect the loaded package
puts package.inspect

Using packages in your program

Once you have created or loaded a package, you can use it within your Ruby application to access its content, data, and other properties.

# Accessing package metadata
puts "Package Name: #{package.metadata['name']}"
puts "Package Version: #{package.metadata['version']}"

# Accessing content
package.content.each do |filename, content_type|
  puts "Content File: #{filename}, Content Type: #{content_type}"
end

# Accessing data
animals_data = package.data['animals.yaml']
puts "Animals Data: #{animals_data.inspect}"

# Accessing routes
package.routes.each do |route, destination|
  puts "Route: #{route}, Destination: #{destination}"
end

# Accessing storage definitions
package.storage['datasets'].each do |dataset|
  puts "Dataset Name: #{dataset['name']}, Source: #{dataset['source']}, Format: #{dataset['format']}"
end

Contributing

We welcome contributions to the Capsium gem. If you would like to contribute, please fork the repository and submit a pull request.

Running tests

To run the tests, use the following command:

rspec

License

Capsium is released under the MIT License. See the LICENSE file for more details.

capsium

Development

Runtime