capsium

= 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.

== Testing out how it works

Download the mn-samples-iso built site: https://github.com/metanorma/mn-samples-iso/actions/runs/8862815829/artifacts/1453746303[mn-samples-iso-Linux].

Then run these commands:

[source,bash]

$ 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:

[source,ruby]

gem 'capsium'

Then, run the following command to install it:

[source,bash]

bundle install

Alternatively, you can install the gem directly using:

[source,bash]

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:

[source,bash]

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:

[source,bash]

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

.Sample pack command

[source,bash]

capsium package pack -f spec/fixtures/bare_package

====

== CLI: Reactor

=== Starting a reactor on your package

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

[source,bash]

capsium reactor serve my_package.cap

== Programmatically managing packages

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

=== Creating packages

[source,ruby]

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:

[source,ruby]

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.

[source,ruby]

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:

[source,bash]

rspec

== License

Copyright Ribose.

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