SPLAY Remote control API

The installation of the SPLAY controller includes a remote control server that responds to JSON-RPC calls over HTTP. This allows users to send commands to the controller remotely, from any computer that has network connectivity with the SPLAY controller.

The remote control server is running on http://ip-of-controller:2222/json-rpc. The list of available calls is as follows:

At the end, a short example of a sequence of remote calls is presented, as guide for starters.

new_user(username, hashed_password, admin_username, admin_hashedpassword)

Description

This call commands the SPLAY remote control server to add to the database a user that will be able to start and kill her own SPLAY jobs.

Authorization

Only an Administrator can create users. Both new user and Administrator's passwords must be hashed with the SHA1 method before being sent.

Return values

  • If the user was successfully added:
    • Name Type Value/Description
    result['ok'] boolean true


  • If something wrong happened:
    • Name Type Value/Description
    result['ok'] boolean false
    result['error'] string Description of the problem.

list_users(admin_username, admin_hashedpassword)

Description

This call asks the SPLAY remote control server for the list of users.

Authorization

Only an Administrator can ask the users' list. The password of the Administrator must be hashed with the SHA1 method before being sent.

Return values

  • If the Administrator was successfully authenticated:
    • Name Type Value/Description
    result['ok'] boolean true
    result['user_list'] Array Contains an array of tables, each containing two key-value pairs:
       result['user_list'][n]['id'] (number)
       result['user_list'][n]['username'] (string)


  • If something wrong happened:
    • Name Type Value/Description
    result['ok'] boolean false
    result['error'] string Description of the problem.

remove_user(username, admin_username, admin_hashedpassword)

Description

This call commands the SPLAY remote control server to remove a user from the database.

Authorization

Only an Administrator can remove users. The password of the Administrator must be hashed with the SHA1 method before being sent.

Return values

  • If the user was successfully removed:
    • Name Type Value/Description
    result['ok'] boolean true


  • If something wrong happened:
    • Name Type Value/Description
    result['ok'] boolean false
    result['error'] string Description of the problem.

change_passwd(username, hashed_currentpassword, hashed_newpassword)

Description

This call commands the SPLAY remote control server to change the password of a user.

Authorization

Only the user itself has the authorization to change her own password. Both passwords (the current and the new one) must be hashed with the SHA1 method before being sent.

Return values

  • If the password was successfully changed:
    • Name Type Value/Description
    result['ok'] boolean true


  • If something wrong happened:
    • Name Type Value/Description
    result['ok'] boolean false
    result['error'] string Description of the problem.

start_session(username, hashed_passwd)

Description

This call commands the SPLAY remote control server to start a command session. It will return a token, valid for 24h. The token is a unique string, that can be stored on a file (when using a command line interface), a variable (when using scripts) or a cookie (when using HTML/Javascript).

Authorization

Any user can start a session. The user's password must be hashed with the SHA1 method before being sent.

Return values

  • If the user was successfully authenticated:
    • Name Type Value/Description
    result['ok'] boolean true
    result['session_id'] string The unique session ID, valid for 24h
    result['expires_at'] string The date and time when the session ID expires


  • If something wrong happened:
    • Name Type Value/Description
    result['ok'] boolean false
    result['error'] string Description of the problem.

list_splayds(session_id)

Description

This call asks the SPLAY remote control server for the list of splayds that are registered at the moment.

Authorization

Any user with a valid session can ask for the list of splayds. Only the session ID must be provided as credentials.

Return values

  • If the session ID is valid:
    • Name Type Value/Description
    result['ok'] boolean true
    result['splayd_list'] Array Contains an array of tables, each containing three key-value pairs:
       result['splayd_list'][n]['splayd_id'] (number)
       result['splayd_list'][n]['ip'] (string)
       result['splayd_list'][n]['status'] (string)


  • If something wrong happened:
    • Name Type Value/Description
    result['ok'] boolean false
    result['error'] string Description of the problem.

submit_job(description, code, nb_splayds, churn_trace, options, session_id)

Description

This call asks the SPLAY remote control server to submit a job.

Arguments

  • description (string): a short description of the job; it can be an empty string
  • code (string): the code of the job in LUA as a string
  • nb_splayds (number): the number of SPLAY deamons that must perform the job; if NULL or a number smaller than 1, it is forced to be 1 on the server side
  • churn_trace (string): if the string is empty, the server considers that there is no churn; if not, the number of splayds is replaced on the server side by the maximum of splayds given by the churn trace
  • options (key-value table)

Authorization

Any user with a valid session can call this command. Only the session ID must be provided as credentials. The owner of the session ID will be registered as the owner of the job.

Return values

  • If the session ID is valid and the Job is running:
    • Name Type Value/Description
    result['ok'] boolean true
    result['job_id'] number The ID of the submitted job.
    result['ref'] string A unique reference code for the submision of the job.


  • If something wrong happened:
    • Name Type Value/Description
    result['ok'] boolean false
    result['error'] string Description of the problem.

list_jobs(session_id)

Description

This call asks the SPLAY remote control server for the list of jobs submitted by the user owning the session ID.

Authorization

Any user with a valid session can ask for the job list. Only the session ID must be provided as credentials.
If the session belongs to an Administrator, the server will return a list of all the jobs submitted by all the users.

Return values

  • If the session ID is valid:
    • Name Type Value/Description
    result['ok'] boolean true
    result['job_list'] Array Contains an array of tables, each containing three key-value pairs:
       result['job_list'][n]['id'] (number)
       result['job_list'][n]['status'] (string)
       result['job_list'][n]['user_id'] (number)
          (if call is made by an Administrator)


  • If something wrong happened:
    • Name Type Value/Description
    result['ok'] boolean false
    result['error'] string Description of the problem.

get_job_details(job_id, session_id)

Description

This call asks the SPLAY remote control server for details about a given job.

Authorization

Only a valid session ID must be provided as credentials. If the owner of the session ID is a regular user, she must be also the owner of the job whose details are being requested. On the other hand, Administrators can get details of any job.

Return values

  • If the session ID is valid:
    • Name Type Value/Description
    result['ok'] boolean true
    result['description'] string Short description of the job; provided by the user at submision
    result['ref'] string Unique reference code of the job; provided by by the SPLAY remote control server at submision
    result['user_id'] number The user who submitted the job (if call is made by an Administrator)
    result['status'] string Current state of the job; can be
    'LOCAL', 'REGISTERING', 'RUNNING', 'ENDED', 'NO_RESSOURCES', 'REGISTER_TIMEOUT', 'KILLED'
    result['host_list'] Array Contains an array of tables indicating the splayds who are running or ran the job; each table contains three key-value pairs:
       result['host_list'][n]['splayd_id'] (number)
       result['host_list'][n]['ip'] (string)
       result['host_list'][n]['port'] (number) 1st port assigned to the daemon


  • If something wrong happened:
    • Name Type Value/Description
    result['ok'] boolean false
    result['error'] string Description of the problem.

get_log(job_id, session_id)

Description

This call asks the SPLAY remote control server for the global log file of a job.

Authorization

Only a valid session ID must be provided as credentials. If the owner of the session ID is a regular user, she must be also the owner of the job whose log is being requested. On the other hand, Administrators can get the logs of any job.

Return values

  • If the session ID is valid:
    • Name Type Value/Description
    result['ok'] boolean true
    result['log'] string The whole log file is dumped as a string and saved in this variable


  • If something wrong happened:
    • Name Type Value/Description
    result['ok'] boolean false
    result['error'] string Description of the problem.

kill_job(job_id, session_id)

Description

This call asks the SPLAY remote control server to kill a job.

Authorization

Only a valid session ID must be provided as credentials. If the owner of the session ID is a regular user, she must be also the owner of the job in order to have the right to kill it. On the other hand, Administrators can get kill any job.

Return values

  • If the session ID is valid:
    • Name Type Value/Description
    result['ok'] boolean true


  • If something wrong happened:
    • Name Type Value/Description
    result['ok'] boolean false
    result['error'] string Description of the problem.

Example of utilization of the remote control calls

A regular interaction with theSPLAY remote control server should follow this sequence:
  • change_passwd (using 'admin, admin' as username, current password) - to set a new Administrator's password
  • new_user - to create new regular users
  • start_session - logging as a regular user
  • list_splayds (using the session_id given at the last step) - to checkif there are available splayds
  • submit_job - to run a job
  • get_job_details / get_log - to get details/logs of the job that was submitted
  • kill_job - if the job does not finish by itself and has to be killed, or the user wants to interrupt it