umich-its-tl/viadutoo

Viadutoo: caching proxy endpoint for Caliper event data

1.1.0 2016-06-13 17:17 UTC

This package is auto-updated.

Last update: 2024-03-17 22:20:45 UTC


README

About

Viadutoo (From the Portuguese word for viaduct, "viaduto". Pronounced as "vee-uh-DOO-too" or in IPA: [vi.a.dˈu.tʊ].) is a kind of caching proxy endpoint for Caliper event data. As a proxy, its purpose is to accept Caliper event payloads from sensors as quickly as possible, then resend them to a preconfigured upstream endpoint. If the upstream endpoint is unable to accept the event payload for some reason, the caching feature will store the event data in a database for future processing.

Requirements

  • PHP 5.4 or greater
  • One of the following PHP HTTP client extensions:
    • curl (usually this is already included with PHP interpreter)
    • pecl_http
  • Composer (not strictly required, but highly recommended)

Usage

  • Update the composer.json file in the root directory of your project as follows:

    • The require section should include the following:

      {
          "require": {
              "php": ">=5.4",
              "umich-its-tl/viadutoo": "1.1.0"
          }
      }
    • If a repository is not specified, Composer will install Viadutoo from Packagist (https://packagist.org/packages/umich-its-tl/viadutoo). However, to specify a GitHub repository as the source instead, include the following in the repositories section:

      {
          "repositories": [
              {
                  "type": "vcs",
                  "url": "https://github.com/tl-its-umich-edu/viadutoo"
              }
          ]
      }

      This is one way to specify your own repository, for example, if you want to modify your own fork of Viadutoo. You would specify the URL of your own repository.

  • Use Composer to install the package with the command:

    composer install

    Composer will create the vendor directory to hold the package and other related information.

  • Composer will create PHP classes to help you load Viadutoo (and any other packages it has loaded) into your application. In your PHP code, use it like:

    /*
     * If necessary, use set_include_path() to ensure the directory
     * containing the "vendor" directory is in the PHP include path.
     */
    require_once 'vendor/autoload.php';  // Composer loader for Viadutoo, etc.
  • Initialize and use Viadutoo in your PHP code like this:

    $proxy = (new MessageProxy())
        ->setTransportInterface(
            (new CurlTransport()) // Recommended transport with cURL, supports Basic Auth and OAuth 1.0
                ->setAuthZType(CurlTransport::AUTHZ_TYPE_OAUTH1, 'OAuth 1.0 key', 'OAuth 1.0 secret') // Optional authZ
        )
        ->setEndpointUrl('http://example.com/endpoint')
        ->setTimeoutSeconds(10)
        ->setAutostoreOnSendFailure(true)
        ->setStorageInterface(
            new MysqlStorage(
                'mysql.example.org', 'dbUser', 'dbPassword',
                'dbName', 'viadutoo_events'
            )
        );
    // ...
    try {
        $proxy
            ->setHeaders($headers)
            ->setBody($jsonBody)
            ->send();
    } catch (Exception $exception) {
        error_log($exception->getMessage());
    }

    For a more detailed example of using Viadutoo in an application, see public/index.php.

Example

An example application is included in the public directory. Execute it as:

cd public
php -S 127.0.0.1:8989

The application is written to send all data to http://lti.tools/caliper/event?key=viadutoo. Simply configure a Caliper sensor to send events to http://127.0.0.1:8989/ and they will be sent on to the lti.tools endpoint.