INDEX

Basics

This section explains the steps to take to make working applications and a spacelets (app for short):; what files are needed, how to make the manifest file etc. The Technical documentation section is referenced often and many details can be read from there.

Have fun making your apps and share them with the world.

The beginning

There are number of possibilities what can be done with Spaceify. In Spaceify the possibilities are tied to services and application types. A good starting point to start developing an app is its type.

Type Description
Sandboxed application An application type providing or requiring services and performing computation in a sandboxed Dcoker container envonrment. Probably the most commond type because of its suitability to many tasks.
Spacelet Sapcelets and sandboxed applications are technically identical. The fundamental difference between them is spacelets capability of interacting with web pages. Spacelet are therefore the go to application type if the app needs to have direct interaction with web pages or alter the web page somehow.
Native Debian This application type is the most powerful type. NAtive applications do not run in sandboxed. They run directly on the host machine and have direct access to the hardware. This makes native applications suitable for example making device drivers.
Sandboxed Debian The definition of sandboxed Debian applications is under development.

The next step is to think about the services the app provides or requires. Spaceify does not impose restrictions for apps that they should provide or require services. However, apps confined in sandboxes without provided or required services are quite useless. If they do not have connections to outside world or the outisde world can not connect to them they just waste host machines resources. On the other hand, with native Debian applications the situation is different. They have direct access to the host machine and its hardware and they might actually serve some purposed even without services. Note about spacelets: because spacelets are designed to work with web pages it is a good practise to provide at least one open service. Only open services are accessible from web pages and spacelets without the possibility of interacting with web pages defies the purpose of spacelets.

The files

At minimum applications requires only the manifest file. In some cases this might be all that is needed (e.g. with modified or customized Docker image) but most likely not. Usually at least some executable file is required for the application.

application
+-- spaceify.manifest

Applications and spacelets can optionally have images, icon, readme file and tile.

application
+-- spaceify.manifest
+-- readme.html
+-- www
    +-- tile.html
    +-- images
        +-- icon image
        +-- image files
  • The image files are used on the Spaceify registry spaceify.org web page. The images are displayed in a slideshow on application package information page.
  • The icon image is displayed on application or spacelet tile and also on the application package information page.
  • The readme.html file is an HTML formatted text displayed on the application package information page.
  • The tile.html file is a custom tile. The tile is displayed on the edge node launch web page.

In addition to these mandatory and optional files applications and spacelets can have any number of files they need; files Spaceify does not need to know.

spaceify.manifest

The manifest file defines an application or a spacelet. In the technical documentation spaceify.manifest subsection are details what a manifest file should contain. Manifest for a spacelet requires more fields than an application but the basic fields are the same. Manifest must contain information about the provided and required services, it must declare the type of the app, it must name the application in an unique way and it must tell the edge node how to start the app. The additional fields required for spacelets are used to provide information to the injection process (more about this below).

API

Spaceify is build around Node.js and the API classes are written in Node.js thus making them available only for other Node.js programs. However, in the lowest level of the Spaceify core is the JSON-RPC API which is based on JSON objects (JavaScript Object Notation), RPC requests (Remote Procedure Call) and WebSocket connections. This API is available to programs written in any language as long as they can establish a WebSocket connection with the core and make JSON-RPC requests to use the methods the API provides.

JSON-RPC API

The basic process of making an application with the JSON-RPC API is outlined below. The process in the pseudo/Node.jsish code should be easy enough to adopt to a any programming language. The minimum requirement for implementation is WebSocket connectivity and server(s) for the provided services. The servers do not have to be WebSocket servers. Spaceify natively supports JSON-RPC and WebSockets but applications can have "alien" connectivity and servers (see provides_services). Spaceify provides a configuration file, located in /api/www/libs/config.json, for applications. Please use it to avoid problems in the future if the configuration changes.

function main()
  {
  try {
    // Load configuration file
    JSON config = new JSON("/var/lib/spaceify/code/config.json");

    // Spaceify core connection
    WebSocketRPCClient rpcCore = new WebSocketRPCClient();
    rpcCore.sync.connect({hostname: config.EDGE_IP, port: config.CORE_PORT_WEBSOCKET});
 
    // Create an unencrypted WebSocket JSON-RPC server for each provided service
    WebSocketRPCServer rpcService = new WebSocketRPCServer();
    rpcService.connect.sync({hostname: null, port: config.FIRST_SERVICE_PORT});  

    // Create an encrypted (TLS) WebSocket JSON-RPC server for each provided service
    String caCrt = config.API_WWW_PATH + config.SPACEIFY_CRT;
    String key = config.APPLICATION_TLS_PATH + config.SERVER_KEY;
    String crt = config.APPLICATION_TLS_PATH + config.SERVER_CRT;
    WebSocketRPCServer rpcServiceSecure = new WebSocketRPCServer();
    rpcServiceSecure.connect.sync({hostname: null, port: config.FIRST_SERVICE_PORT_SECURE,
        caCrt: caCrt, key: key, crt: crt});  

    // App should provide both unsecure and secure services but secure service is not mandatory.
    // Use config.FIRST_SERVICE_PORT + 1, config.FIRST_SERVICE_PORT + 2, etcetera,
    // if there are more than one provided service.

    // Expose a method for external calls
    rpcService.exposeMethod("doSomething", doSomething);
    rpcServiceSecure.exposeMethod("doSomething", doSomething);      

    // Register the provided service to the Spaceify core
    rpcCore.sync.callRpc("registerService", "spaceify.org/services/example/spacelet1");

    // Create web servers (http and possibly https) here if application provides them
    // ?

    // Print success to stdout to finish the initialization
    stdout.print(config.APPLICATION_INITIALIZED);
    }
  catch(Exception exp)
    {
    // Print failure to stdout to cancel the initialization. Optionally pass error string to core between ";; .... ::"
    // stdout.print(";;" + exp.toString() + "::");
    stdout.print(config.APPLICATION_UNINITIALIZED);
    }
  }

function doSomething(Int a, Int b)
  {
  // ...
  return c;
  }

JavaScript API classes

Writing applications using the classes Spaceify provides is so much easier than using the JSON-RPC API. There are four classes that can be used in Node.js programs and web pages.

  • Spacelet

A class that is intended to be used on web pages to start spacelets and establish connections to their open services.

  • SpaceifyApplication

This class is used in Node.js programs to initialize applications and spacelets. The class automatically creates servers for provided services, connects to required services and creates web servers if so requested. The servers and connections currently support only WebSockets. When used in web pages this class establishes connections to open services of applications.

  • Service

The Spacelet and SpaceifyApplication classes use this class to handle their required and provided services. It is not intended to be instantiated by clients. The instances Spacelet and SpaceifyApplication classes create are returned to client programs using methods in them.

  • SpaceifyCore

SapceifyCore is a higher level class offering easy access to the JSON-RPC API methods.

JavaScript API classes on web pages

The above four classes are minified to a JavaScript file, that can be used on web pages: spaceify.api.js.

See the remote operation how to safely load the classes in tiles and applciation web pages.

Close
copyright © Spaceify.org 2014