nutella_framework 0.4.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 98a1d74bc599d78623959deb2d80d7ef4b5527b0
-  data.tar.gz: 229db1d35c9f3000f6510fa44e075878e21b7f07
+  metadata.gz: 0ee0147d7ad4b06c602ad742ad464804686a73af
+  data.tar.gz: 5255b9ac953ca5d4a2608943ed6d7fab61cebaaf
 SHA512:
-  metadata.gz: 0673b2e12cd08dd77e2359b3aa05f7d0d9d6b36e415de55f0df13ef201887fd5c1e0303e695bef502cc2b877df6b72a4aa405d358375ff0498635a4178337322
-  data.tar.gz: 274b0ea11c7671bb8cb42f1d1179026f5a6cfb04d3af52a60d91b3e3a8d97d804457b248203733b821cc2b75bd7ff390c2e1089822627a5525bbea7a8640ae74
+  metadata.gz: e93582f785ccdebe69dd852033edd700935bc957a29844633d07d7001459d928e0b20b1d72f9740e67941a68c3fca1ab67f871ac2c9b3a1c8288fe540fe593f6
+  data.tar.gz: 23ac44867911110658384dce2379c8a3336868ce39e7f8cec1d07ff07ed04fb3a2790c22186d218f6cfe39e1e36ccf41c301a95953e340c174f957e21b6fa969

data/Gemfile

@@ -1,6 +1,5 @@
 source "http://rubygems.org"
 
-gem 'ansi', '~> 1.4', '>= 1.4.3'
 gem 'semantic', '~> 1.3', '>=1.3'
 gem 'logging', '~> 1.8', '>=1.8.2'
 gem 'git', '~> 1.2', '>=1.2.8'
@@ -8,7 +7,7 @@ gem 'sinatra', '~>1.4.5', '>=1.4.5'
 gem 'thin', '~>1.6.3', '>=1.6.3'
 gem 'nokogiri', '~>1.6.3', '>=1.6.3'
 gem 'slop', '~>4.0.0', '>=4.0.0'
-gem 'nutella_lib','~>0.4.0', '>=0.4.0'
+gem 'nutella_lib','~>0.4.1', '>=0.4.1'
 
 
 group :development do

data/README.md

@@ -3,18 +3,18 @@
 [![Build Status](https://travis-ci.org/nutella-framework/nutella_framework.svg?branch=master)](https://travis-ci.org/nutella-framework/nutella_framework)
 [![Code Climate](https://codeclimate.com/github/nutella-framework/nutella_framework/badges/gpa.svg)](https://codeclimate.com/github/nutella-framework/nutella_framework)
 
-# Nutella 
-Nutella is a framework to build and run classroom narratives. It's still _very_ under development so any help [finding and fixing bugs](https://github.com/nutella-framework/nutella_framework/issues) will be greatly appreciated!
+nutella is a framework to build and run RoomApps. It's still _very_ under development so any help [finding and fixing bugs](https://github.com/nutella-framework/nutella_framework/issues) will be greatly appreciated!
 
 # Installing
-Nutella is written in ruby but it leverages lots of technologies that already exists. Therefore, before you can successfully install nutella, you need to install (if you don't have them already):
+Nutella is written in ruby but it leverages a bunch of other technologies that need to be installed. You will need:
 
-1. _ruby_ (version >= 2.1.0). Do yourself a favor and use [RVM](https://rvm.io/rvm/install).
-1. _git_ (version >= 1.8.0). Do yourself a favor and use [Homebrew](http://brew.sh/) if you are on OSX.
-1. _tmux_ (version >= 1.8.0). Do yourself a favor and use [Homebrew](http://brew.sh/) if you are on OSX.
+1. _ruby_ (version >= 2.1.0). Do yourself a favor and use [RVM](https://rvm.io/rvm/install) to install Ruby.
+1. _git_ (version >= 1.8.0). Do yourself a favor and use [Homebrew](http://brew.sh/) to install git, if you are on OSX.
+1. _tmux_ (version >= 1.8.0). Do yourself a favor and use [Homebrew](http://brew.sh/) to install tmux, if you are on OSX.
 1. _node.js_ (version >= 0.10.0). Yes, really, you need to install node becaue we use it to run the broker that handles all communications between all the pieces of the framework. Do yourself a favor and use [nvm](https://github.com/creationix/nvm).
+1. _mongoDB_ (optional). You'll need mongoDB if you want to use it with `nutella.persist`.
 
-Once you have all the pieces that you need, to install nutella simply do:
+Once you have all of these, to install nutella simply do:
 ```
 gem install nutella_framework
 ```
@@ -23,19 +23,19 @@ Once the installation is complete you should be able to type `nutella` in your s
 ## nutella checkup
 If you are reading this you probably already saw the warning: "Looks like this is a fresh installation of nutella. Please run 'nutella checkup' to check all dependencies are installed".
 
-Nutella is written in ruby but is designed to run bots and interfaces written in virtually any programming language. All communications among these components are routed through an _MQTT broker_ which needs to be installed (together with its dependencies) before nutella can actually work correctly. Therefore **right after your install nutella** you should run: 
+nutella is written in ruby but it's designed to run bots and interfaces written in virtually any programming language. All communications among these components are handled by an _MQTT broker_ which needs to be installed (together with its dependencies) before nutella can actually work correctly. Therefore **right after your install nutella** you should run:
 ```
 nutella checkup
 ```
 This will install the [Mosca](http://www.mosca.io/) MQTT broker and make sure all the dependencies required by nutella are installed as well.
 
-Congratulations! Nutella is ready to use!
+Congratulations! nutella is ready to use!
 
 
 # Where next?
-If you already have an application you want to tinker with (like [RoomQuake](https://github.com/ltg-uic/roomquake)) simply checkout the application to a local folder, `cd /to/my/local/folder` and start tinkering away. Not sure what to do? Check out our [nutella Command Line Tool man page](https://github.com/nutella-framework/nutella_framework/wiki/Nutella-Command-Line-Interface).
+If you already have an application you want to tinker with (like [RoomQuake](https://github.com/ltg-uic/roomquake)) simply checkout the application to a local folder, `cd /to/my/local/folder` and start tinkering away. Not sure how? Check out the [man page for the nutella command line tool](https://github.com/nutella-framework/nutella_framework/wiki).
 
-If you want to create your own application, check out the [new app tutorial](https://github.com/nutella-framework/nutella_framework/wiki/New-application-tutorial).
+If you want to create your own application, hold on tight, a tutorial is coming soon.
 
 
 # Contributing

data/Rakefile

@@ -17,8 +17,8 @@ Jeweler::Tasks.new do |gem|
   gem.name = "nutella_framework"
   gem.homepage = "https://github.com/nutella-framework/nutella_framework"
   gem.license = "MIT"
-  gem.summary = %Q{A framework to create and run classroom narratives}
-  gem.description = %Q{Nutella is a framework to create and run classroom narratives}
+  gem.summary = %Q{A rails-inspired framework for RoomApps}
+  gem.description = %Q{utella is a framework to create and run RoomApps}
   gem.email = "tebemis@gmail.com"
   gem.authors = ["Alessandro Gnoli"]
   # dependencies defined in Gemfile

data/VERSION

@@ -1 +1 @@
-0.4.0
+0.4.1

data/framework_components/runs_list_bot/app_runs_list_bot.rb

@@ -1,15 +1,51 @@
-require 'nutella_lib'
+require_relative '../../nutella_lib/framework_core'
+
+# Define a couple of utility functions to better deal with the runs list
+def all_apps( runlist_file )
+  runlist_h = JSON.parse(IO.read(runlist_file))
+  runlist_h.keys
+end
+
+def runs_for_app( runlist_file, app_id )
+  runlist_h = JSON.parse(IO.read(runlist_file))
+  # If there is no app with this id, then return false and do nothing
+  return [] if runlist_h[app_id].nil?
+  runs = runlist_h[app_id]['runs']
+  runs.nil? ? [] : runs
+end
+
+
+# Parse configuration file and runlist from the command line
+config_file = ARGV[0]
+runlist_file = ARGV[1]
+
+# Try to parse both config file and runlist and terminate if we can't
+begin
+  config_h = JSON.parse(IO.read(config_file))
+  runlist_h = JSON.parse(IO.read(runlist_file))
+rescue
+  # something went wrong
+  abort 'Impossible to parse configuration and/or runlist files!'
+end
+
+# Initialize this bot as framework component
+nutella.f.init(config_h['broker'], 'app_runs_list_bot')
 
-# This needs to be initialized as framework component like so:
-# nutella.init_as_app_component('localhost', 'app_runs_list_bot')
-nutella.init('localhost', 'my_app_id', 'no_run_id', 'app_runs_list_bot')
 
 # Listen for runs_list requests (done by app components when they connect)
-nutella.net.app.handle_requests('app_runs_list', lambda do |req, from|
-  from['app_id'] # Use this info to fetch the appropriate runs
-  ['run_1', 'run_2', 'run_3'] # Return an array of names!
+nutella.f.net.handle_requests_on_all_apps('app_runs_list', lambda do |req, app_id, from|
+  runs_for_app(runlist_file, app_id)
 end)
 
-# Whenever the list is updated, fire an update to the right app
 
-nutella.net.listen
+# Whenever the runs list is updated, fire an updated runlist to all the apps
+p = JSON.parse(IO.read(runlist_file))
+while sleep .5
+  n = JSON.parse IO.read runlist_file
+  if p!=n
+    all_apps.each do |app_id, _|
+      nutella.f.net.publish_to_app(app_id, 'app_runs_list', runs_for_app(app_id, runlist_h))
+    end
+    p = n
+  end
+end

data/framework_components/runs_list_bot/startup

@@ -0,0 +1,8 @@
+#!/bin/sh
+
+BASEDIR=$(dirname $0)
+
+# Pass the configuration file and the runlist
+
+ruby $BASEDIR/app_runs_list_bot.rb $1 $2 > /dev/null 2>&1 &
+echo $! > $BASEDIR/.pid

data/lib/commands/start.rb

@@ -144,6 +144,7 @@ module Nutella
       return false unless start_app_bots(app_id, app_path)
       # Start all run-level bots
       false unless start_run_bots( app_path, app_id, run_id, params )
+      true
     end
 
 
@@ -238,6 +239,8 @@ module Nutella
       command = "#{component_dir}/startup #{nutella_config_file} #{runs_list_file}"
       pid = fork
       exec(command) if pid.nil?
+      # Give it a second so they can start properly
+      sleep 1
       # All went well so we return true
       true
     end

data/lib/config/current_app_utils.rb

@@ -13,7 +13,13 @@ module Nutella
       nutella_json_file = "#{cur_app_dir}/nutella.json"
       # Check that there is a nutella.json file in the main directory of the application
       if File.exist? nutella_json_file
-        conf = JSON.parse( IO.read(nutella_json_file) )
+        begin
+          conf = JSON.parse( IO.read(nutella_json_file) )
+        rescue
+          console.warn 'The nutella.json file for this application does not contain properly formatted JSON'
+          return false
+        end
+
         if conf['nutella_version'].nil?
           return false
         end

data/lib/config/runlist.rb

@@ -1,4 +1,5 @@
 require 'config/persisted_hash'
+require 'tmux/tmux'
 
 module Nutella
 
@@ -21,9 +22,17 @@ module Nutella
     end
 
 
-    # Returns all the +run_id+s for ALL applications
+    # Returns a list of all the apps in the runlist
     #
-    # @return [Array<String>] list of +run_id+s associated to the specified app_id
+    # @return [Array<String>] an array containing the app_ids of all the apps in the runlist
+    def all_apps
+      @ph.to_h.keys
+    end
+
+
+    # Returns all the +run_id+s for ALL applications (i.e. the runslist)
+    #
+    # @return [Hash] the run list with all app_ids and run_ids
     def all_runs
       @ph.to_h
     end
@@ -31,7 +40,7 @@ module Nutella
 
     # Returns all the +run_id+s for a certain application
     #
-    # @param [String] app_id the id of the application we want to find run_ids for
+    # @param [String] app_id of the application we want to find run_ids for
     # @return [Array<String>] list of +run_id+s associated to the specified app_id
     def runs_for_app( app_id )
       # If there is no app, then return false and do nothing

data/nutella_framework.gemspec

@@ -2,17 +2,17 @@
 # DO NOT EDIT THIS FILE DIRECTLY
 # Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
 # -*- encoding: utf-8 -*-
-# stub: nutella_framework 0.4.0 ruby lib
+# stub: nutella_framework 0.4.1 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "nutella_framework"
-  s.version = "0.4.0"
+  s.version = "0.4.1"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib"]
   s.authors = ["Alessandro Gnoli"]
-  s.date = "2015-03-13"
-  s.description = "Nutella is a framework to create and run classroom narratives"
+  s.date = "2015-03-16"
+  s.description = "utella is a framework to create and run RoomApps"
   s.email = "tebemis@gmail.com"
   s.executables = ["nutella"]
   s.extra_rdoc_files = [
@@ -39,6 +39,7 @@ Gem::Specification.new do |s|
     "framework_components/main_interface/views/not_found_404.erb",
     "framework_components/order.json.example",
     "framework_components/runs_list_bot/app_runs_list_bot.rb",
+    "framework_components/runs_list_bot/startup",
     "lib/commands/broker.rb",
     "lib/commands/checkup.rb",
     "lib/commands/compile.rb",
@@ -63,9 +64,10 @@ Gem::Specification.new do |s|
     "lib/logging/nutella_logger.rb",
     "lib/logging/nutella_logging.rb",
     "lib/nutella_framework.rb",
-    "lib/nutella_lib_framework/api.rb",
     "lib/tmux/tmux.rb",
     "nutella_framework.gemspec",
+    "nutella_lib/framework_core.rb",
+    "nutella_lib/framework_net.rb",
     "test/commands/test_cmd_cli_params_parsing.rb",
     "test/commands/test_command_template.rb",
     "test/config/test_current_app_utils.rb",
@@ -78,13 +80,12 @@ Gem::Specification.new do |s|
   s.homepage = "https://github.com/nutella-framework/nutella_framework"
   s.licenses = ["MIT"]
   s.rubygems_version = "2.4.3"
-  s.summary = "A framework to create and run classroom narratives"
+  s.summary = "A rails-inspired framework for RoomApps"
 
   if s.respond_to? :specification_version then
     s.specification_version = 4
 
     if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
-      s.add_runtime_dependency(%q<ansi>, [">= 1.4.3", "~> 1.4"])
       s.add_runtime_dependency(%q<semantic>, [">= 1.3", "~> 1.3"])
       s.add_runtime_dependency(%q<logging>, [">= 1.8.2", "~> 1.8"])
       s.add_runtime_dependency(%q<git>, [">= 1.2.8", "~> 1.2"])
@@ -92,7 +93,7 @@ Gem::Specification.new do |s|
       s.add_runtime_dependency(%q<thin>, [">= 1.6.3", "~> 1.6.3"])
       s.add_runtime_dependency(%q<nokogiri>, [">= 1.6.3", "~> 1.6.3"])
       s.add_runtime_dependency(%q<slop>, [">= 4.0.0", "~> 4.0.0"])
-      s.add_runtime_dependency(%q<nutella_lib>, [">= 0.4.0", "~> 0.4.0"])
+      s.add_runtime_dependency(%q<nutella_lib>, [">= 0.4.1", "~> 0.4.1"])
       s.add_development_dependency(%q<shoulda>, [">= 3", "~> 3"])
       s.add_development_dependency(%q<yard>, [">= 0.8.7", "~> 0.8"])
       s.add_development_dependency(%q<rdoc>, [">= 4.0", "~> 4.0"])
@@ -100,7 +101,6 @@ Gem::Specification.new do |s|
       s.add_development_dependency(%q<jeweler>, [">= 2.0.1", "~> 2.0.1"])
       s.add_development_dependency(%q<simplecov>, [">= 0", "~> 0"])
     else
-      s.add_dependency(%q<ansi>, [">= 1.4.3", "~> 1.4"])
       s.add_dependency(%q<semantic>, [">= 1.3", "~> 1.3"])
       s.add_dependency(%q<logging>, [">= 1.8.2", "~> 1.8"])
       s.add_dependency(%q<git>, [">= 1.2.8", "~> 1.2"])
@@ -108,7 +108,7 @@ Gem::Specification.new do |s|
       s.add_dependency(%q<thin>, [">= 1.6.3", "~> 1.6.3"])
       s.add_dependency(%q<nokogiri>, [">= 1.6.3", "~> 1.6.3"])
       s.add_dependency(%q<slop>, [">= 4.0.0", "~> 4.0.0"])
-      s.add_dependency(%q<nutella_lib>, [">= 0.4.0", "~> 0.4.0"])
+      s.add_dependency(%q<nutella_lib>, [">= 0.4.1", "~> 0.4.1"])
       s.add_dependency(%q<shoulda>, [">= 3", "~> 3"])
       s.add_dependency(%q<yard>, [">= 0.8.7", "~> 0.8"])
       s.add_dependency(%q<rdoc>, [">= 4.0", "~> 4.0"])
@@ -117,7 +117,6 @@ Gem::Specification.new do |s|
       s.add_dependency(%q<simplecov>, [">= 0", "~> 0"])
     end
   else
-    s.add_dependency(%q<ansi>, [">= 1.4.3", "~> 1.4"])
     s.add_dependency(%q<semantic>, [">= 1.3", "~> 1.3"])
     s.add_dependency(%q<logging>, [">= 1.8.2", "~> 1.8"])
     s.add_dependency(%q<git>, [">= 1.2.8", "~> 1.2"])
@@ -125,7 +124,7 @@ Gem::Specification.new do |s|
     s.add_dependency(%q<thin>, [">= 1.6.3", "~> 1.6.3"])
     s.add_dependency(%q<nokogiri>, [">= 1.6.3", "~> 1.6.3"])
     s.add_dependency(%q<slop>, [">= 4.0.0", "~> 4.0.0"])
-    s.add_dependency(%q<nutella_lib>, [">= 0.4.0", "~> 0.4.0"])
+    s.add_dependency(%q<nutella_lib>, [">= 0.4.1", "~> 0.4.1"])
     s.add_dependency(%q<shoulda>, [">= 3", "~> 3"])
     s.add_dependency(%q<yard>, [">= 0.8.7", "~> 0.8"])
     s.add_dependency(%q<rdoc>, [">= 4.0", "~> 4.0"])

data/nutella_lib/framework_core.rb

@@ -0,0 +1,68 @@
+require 'nutella_lib'
+require 'config/runlist'
+
+# APIs sub-modules
+require_relative 'framework_net'
+
+
+module Nutella
+
+  # Accessor to the framework APIs sub-module
+  def Nutella.f
+    Nutella::Framework
+  end
+
+
+
+  #  Framework-level APIs sub-module
+  module Framework
+
+    # Initializes this component as a framework component
+    # @param [String] broker_hostname
+    # @param [String] component_id
+    def self.init( broker_hostname, component_id )
+      Nutella.app_id = nil
+      Nutella.run_id = nil
+      Nutella.component_id = component_id
+      Nutella.resource_id = nil
+      Nutella.mqtt = SimpleMQTTClient.new broker_hostname
+    end
+
+    # Accessors for sub-modules
+    def self.net; Nutella::Framework::Net; end
+    def self.log; Nutella::Framework::Log; end
+
+
+    # Utility functions
+
+
+    # Parse command line arguments for framework level components
+    #
+    # @param [Array] args command line arguments array
+    # @return [String] broker
+    def self.parse_args(args)
+      if args.length < 1
+        STDERR.puts 'Couldn\'t read broker address from the command line, impossible to initialize component!'
+        return
+      end
+      return args[0]
+    end
+
+    # Extracts the component name from the folder where the code for this component is located
+    #
+    # @return [String] the component name
+    def self.extract_component_id
+      Nutella.extract_component_id
+    end
+
+    # Sets the resource id
+    #
+    # @param [String] resource_id the resource id (i.e. the particular instance of this component)
+    def self.set_resource_id( resource_id )
+      Nutella.set_resource_id resource_id
+    end
+
+
+  end
+
+end

data/{lib/nutella_lib_framework/api.rb → nutella_lib/framework_net.rb}

@@ -1,43 +1,8 @@
-require 'nutella_lib'
-require 'config/runlist'
-
 module Nutella
 
+  module Framework
 
-  # Initializes this component as a framework component
-  # @param [String] broker_hostname
-  # @param [String] component_id
-  def self.init_as_f_component( broker_hostname, component_id )
-    @app_id = nil
-    @run_id = nil
-    @component_id = component_id
-    @resource_id = nil
-    @mqtt = SimpleMQTTClient.new broker_hostname
-  end
-
-
-  # Parse command line arguments for framework level components
-  #
-  # @param [Array] args command line arguments array
-  # @return [String] broker
-  def self.parse_f_component_args(args)
-    if args.length < 1
-      STDERR.puts 'Couldn\'t read broker address from the command line, impossible to initialize component!'
-      return
-    end
-    return args[0]
-  end
-
-
-  module Net
-
-    # Provides access to the net.app sub-module
-    def Net.f; Nutella::Net::Framework end
-
-
-    # This module implements the pub/sub and request/response APIs at the framework-level
-    module Framework
-
+    module Net
 
       # @!group Framework-level communication APIs
 
@@ -287,7 +252,7 @@ module Nutella
             # Only handle requests that have proper id set
             return if type!='request' || id.nil?
             # Execute callback and send response
-            m = Net.prepare_message_for_response( callback.call( payload, app_id, run_id, from), id )
+            m = Nutella::Net.prepare_message_for_response( callback.call( payload, app_id, run_id, from), id )
             Nutella.mqtt.publish( mqtt_channel, m )
           rescue JSON::ParserError
             # Make sure that request contains JSON, if not drop the message
@@ -307,7 +272,83 @@ module Nutella
 
       # @!group Framework-level APIs to communicate at the application-level
 
-      # TODO
+
+      # Allows framework-level APIs to subscribe to an app-level channel within a specific run
+      #
+      # @param [String] app_id the specific application we are subscribing to
+      # @param [String] channel the run-level channel we are subscribing to. Can be wildcard.
+      # @param [Proc] callback the callback that is fired whenever a message is received on the channel.
+      #   The passed callback takes the following parameters:
+      #   - [String] message: the received message. Messages that are not JSON are discarded.
+      #   - [String] channel: the framework-level channel the message was received on (optional, only for wildcard subscriptions)
+      #   - [Hash] from: the sender's identifiers (run_id, app_id, component_id and optionally resource_id)
+      def self.subscribe_to_app(app_id, channel, callback)
+        Nutella::Net.subscribe_to(channel, callback, app_id, nil)
+      end
+
+
+      # Allows framework-level APIs to unsubscribe from an app-level channel within a specific run
+      #
+      # @param [String] app_id the specific application we are un-subscribing from
+      # @param [String] run_id the specific run we are un-subscribing from
+      # @param [String] channel the run-level channel we want to unsubscribe from. Can contain wildcard(s).
+      def self.unsubscribe_to_app( app_id, channel )
+        Nutella::Net.unsubscribe_to(channel, app_id, nil)
+      end
+
+
+      # Allows framework-level APIs to publish to an app-level channel within a specific run
+      #
+      # @param [String] app_id the specific application we are publishing to
+      # @param [String] channel the run-level channel we want to publish the message to. *CANNOT* contain wildcard(s)!
+      # @param [String] message the message we are publishing. This can be,
+      #   nil/empty (default), a string, a hash and, in general, anything with a .to_json method.
+      def self.publish_to_app(app_id, channel, message)
+        Nutella::Net.publish_to(channel, message, app_id, nil)
+      end
+
+
+      # Allows framework-level APIs to make a synchronous request to a run-level channel within a specific run
+      #
+      # @param [String] app_id the specific application we are making the request to
+      # @param [String] run_id the specific run we are making the request to
+      # @param [String] channel the channel we want to make the request to. *CANNOT* contain wildcard(s)!
+      # @param [Object] request the body of request. This can be,
+      #   nil/empty (default), a string, a hash and, in general, anything with a .to_json method.
+      def self.sync_request_to_app( app_id, channel, request)
+        Nutella::Net.sync_request_to(channel, request, app_id, nil)
+      end
+
+
+      # Allows framework-level APIs to make an asynchronous request to a run-level channel within a specific run
+      #
+      # @param [String] app_id the specific application we are making the request to
+      # @param [String] run_id the specific run we are making the request to
+      # @param [String] channel the channel we want to make the request to. *CANNOT* contain wildcard(s)!
+      # @param [Object] request the body of request. This can be,
+      #   nil/empty (default), a string, a hash and, in general, anything with a .to_json method.
+      # @param [Proc] callback the callback that is fired whenever a response is received. It takes one parameter (response).
+      def self.async_request_to_app( app_id, channel, request, callback)
+        Nutella::Net.async_request_to(channel, request, callback, app_id, nil)
+      end
+
+
+      # Allows framework-level APIs to handle requests on a run-level channel within a specific run
+      #
+      # @param [String] app_id the specific application requests are coming from
+      # @param [String] run_id the specific run requests are coming from
+      # @param [String] channel we want to listen for requests on. Can contain wildcard(s).
+      # @param [Proc] callback a lambda expression that is fired whenever a message is received.
+      #   The passed callback takes the following parameters:
+      #   - [String] the received message (payload). Messages that are not JSON are discarded.
+      #   - [Hash] the sender's identifiers (run_id, app_id, component_id and optionally resource_id)
+      #   - [*returns* Hash] The response sent back to the client that performed the request. Whatever is returned by the callback is marshaled into a JSON string and sent via MQTT.
+      def self.handle_requests_on_app(app_id, channel, callback)
+        Nutella::Net.handle_requests_on(channel, callback, app_id, nil)
+      end
+
+
+
 
       # @!endgroup
 
@@ -315,10 +356,125 @@ module Nutella
 
       # @!group Framework-level APIs to communicate at the application-level (broadcast)
 
-      # TODO
+
+      # Allows framework-level APIs to subscribe to an app-level channel *for ALL apps*
+      #
+      # @param [String] channel the app-level channel we are subscribing to. Can be wildcard.
+      # @param [Proc] callback the callback that is fired whenever a message is received on the channel.
+      #   The passed callback takes the following parameters:
+      #   - [String] message: the received message. Messages that are not JSON are discarded.
+      #   - [String] app_id: the app_id of the channel the message was sent on
+      #   - [Hash] from: the sender's identifiers (run_id, app_id, component_id and optionally resource_id)
+      def self.subscribe_to_all_apps(channel, callback)
+        # Check the passed callback has the right number of arguments
+        raise 'You need to pass a callback with 3 parameters (payload, app_id, from) when subscribing to all apps!' if callback.parameters.length!=3
+        # Pad channel
+        padded_channel = Nutella::Net.pad_channel(channel, '+', nil)
+        mqtt_cb = lambda do |mqtt_message, mqtt_channel|
+          begin
+            type, from, payload, _ = Nutella::Net.extract_fields_from_message mqtt_message
+            app_id = self.extract_app_id mqtt_channel
+            callback.call(payload, app_id, from) if type=='publish'
+          rescue JSON::ParserError
+            # Make sure the message is JSON, if not drop the message
+            return
+          rescue
+            # Check the passed callback has the right number of arguments
+            STDERR.puts "The callback you passed to subscribe has the #{$!}: it needs 'payload', 'app_id' and 'from'"
+          end
+        end
+        # Add to subscriptions, save mqtt callback and subscribe
+        Nutella::Net.subscriptions.push padded_channel
+        Nutella::Net.callbacks.push mqtt_cb
+        Nutella.mqtt.subscribe( padded_channel, mqtt_cb )
+      end
+
+
+      # Allows framework-level APIs to unsubscribe from an app-level channel *for ALL apps*
+      #
+      # @param [String] channel the run-level channel we want to unsubscribe from. Can contain wildcard(s).
+      def self.unsubscribe_from_all_apps( channel )
+        Nutella::Net.unsubscribe_to(channel, '+', nil)
+      end
+
+
+      # Allows framework-level APIs to publish a message to an app-level channel *for ALL apps*
+      #
+      # @param [String] channel the app-level channel we want to publish the message to. *CANNOT* contain wildcard(s)!
+      # @param [Object] message the message we are publishing. This can be,
+      #   nil/empty (default), a string, a hash and, in general, anything with a .to_json method.
+      def self.publish_to_all_apps(channel, message)
+        Nutella.runlist.all_runs.each do |app_id, _|
+          Nutella::Net.publish_to(channel, message, app_id, nil)
+        end
+      end
+
+
+      # Allows framework-level APIs to send a request to a run-level channel *for ALL runs*
+      #
+      # @param [String] channel the app-level channel we want to make the request to. *CANNOT* contain wildcard(s)!
+      # @param [Object] request the body of request. This can be,
+      #   nil/empty (default), a string, a hash and, in general, anything with a .to_json method.
+      # @param [Proc] callback the callback that is fired whenever a response is received. It takes one parameter (response).
+      def self.async_request_to_all_apps(channel, request, callback)
+        Nutella.runlist.all_runs.each do |app_id, _|
+          Nutella::Net.async_request_to(channel, request, callback, app_id, nil)
+        end
+      end
+
+
+      # Allows framework-level APIs to handle requests to a run-level channel *for ALL runs*
+      #
+      # @param [String] channel tha app-level channel we want to listen for requests on. Can contain wildcard(s).
+      # @param [Proc] callback a lambda expression that is fired whenever a message is received.
+      #   The passed callback takes the following parameters:
+      #   - [String] the received message (request). Messages that are not JSON are discarded.
+      #   - [String] app_id: the app_id of the channel the request was sent on
+      #   - [Hash] the sender's identifiers (from containing, run_id, app_id, component_id and optionally resource_id)
+      #   - [*returns* Hash] The response sent back to the client that performed the request. Whatever is returned by the callback is marshaled into a JSON string and sent via MQTT.
+      def self.handle_requests_on_all_apps(channel, callback)
+        # Check the passed callback has the right number of arguments
+        raise 'You need to pass a callback with 3 parameters (request, run_id, from) when handling requests!' if callback.parameters.length!=3
+        # Pad channel
+        padded_channel = Nutella::Net.pad_channel(channel, '+', nil)
+        mqtt_cb = lambda do |request, mqtt_channel|
+          begin
+            # Extract nutella fields
+            type, from, payload, id = Nutella::Net.extract_fields_from_message request
+            app_id  = self.extract_app_id mqtt_channel
+            # Only handle requests that have proper id set
+            return if type!='request' || id.nil?
+            # Execute callback and send response
+            m = Nutella::Net.prepare_message_for_response( callback.call( payload, app_id, from), id )
+            Nutella.mqtt.publish( mqtt_channel, m )
+          rescue JSON::ParserError
+            # Make sure that request contains JSON, if not drop the message
+            return
+          rescue
+            # Check the passed callback has the right number of arguments
+            STDERR.puts "The callback you passed to subscribe has the #{$!}: it needs 'request', 'app_id' and 'from'"
+          end
+        end
+        # Subscribe to the channel
+        Nutella.mqtt.subscribe( padded_channel, mqtt_cb )
+      end
 
       # @!endgroup
 
+      # ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+
+      # Listens for incoming messages. All this function
+      # does is to put the thread to sleep and wait for something to
+      # happen over the network to wake up.
+      def self.listen
+        begin
+          sleep
+        rescue Interrupt
+          # Simply returns once interrupted
+        end
+      end
+
+
       private
 
       def self.extract_run_id_and_app_id( mqtt_channel )
@@ -327,7 +483,13 @@ module Nutella
       end
 
 
-    end
+      def self.extract_app_id( mqtt_channel )
+        sp =  mqtt_channel.sub('/nutella/apps/', '').split('/')
+        return sp[0]
+      end
+
+    end # net
+
+  end # framework
 
-  end
-end
+end # nutella

data/test/framework_apis/test_framework_api.rb

@@ -1,6 +1,6 @@
 require 'helper'
 
-require_relative '../../lib/nutella_lib_framework/api'
+require_relative '../../nutella_lib/framework_core'
 
 
 

metadata

@@ -1,35 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: nutella_framework
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.1
 platform: ruby
 authors:
 - Alessandro Gnoli
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-03-13 00:00:00.000000000 Z
+date: 2015-03-16 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  name: ansi
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 1.4.3
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.4'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 1.4.3
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.4'
 - !ruby/object:Gem::Dependency
   name: semantic
   requirement: !ruby/object:Gem::Requirement
@@ -176,20 +156,20 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.4.0
+        version: 0.4.1
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.4.0
+        version: 0.4.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.4.0
+        version: 0.4.1
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.4.0
+        version: 0.4.1
 - !ruby/object:Gem::Dependency
   name: shoulda
   requirement: !ruby/object:Gem::Requirement
@@ -310,7 +290,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0'
-description: Nutella is a framework to create and run classroom narratives
+description: utella is a framework to create and run RoomApps
 email: tebemis@gmail.com
 executables:
 - nutella
@@ -338,6 +318,7 @@ files:
 - framework_components/main_interface/views/not_found_404.erb
 - framework_components/order.json.example
 - framework_components/runs_list_bot/app_runs_list_bot.rb
+- framework_components/runs_list_bot/startup
 - lib/commands/broker.rb
 - lib/commands/checkup.rb
 - lib/commands/compile.rb
@@ -362,9 +343,10 @@ files:
 - lib/logging/nutella_logger.rb
 - lib/logging/nutella_logging.rb
 - lib/nutella_framework.rb
-- lib/nutella_lib_framework/api.rb
 - lib/tmux/tmux.rb
 - nutella_framework.gemspec
+- nutella_lib/framework_core.rb
+- nutella_lib/framework_net.rb
 - test/commands/test_cmd_cli_params_parsing.rb
 - test/commands/test_command_template.rb
 - test/config/test_current_app_utils.rb
@@ -396,5 +378,5 @@ rubyforge_project:
 rubygems_version: 2.4.3
 signing_key: 
 specification_version: 4
-summary: A framework to create and run classroom narratives
+summary: A rails-inspired framework for RoomApps
 test_files: []