Newsworthy Presidential Mistakes

    principessa

    1.5.0 • Public • Published

    principessa 👸

    Travis Codecov npm semantic-release Commitizen friendly NPM version

    Run a given service with the ability to manage upload / download of files to a Cloud Files service

    Gettings Started

    Example usage

    import principessa from 'principessa'
    import myService from 'my-service'
    import iron_worker from 'iron_worker'
     
    const PAYLOAD = iron_worker.params()
     
    principessa().execute({
      payload: PAYLOAD,
      onRun(options) {
        // run your service with options
        // this should return an promise that resolves when the service is done
        return myService(options)
      },
      onError(errors) {
        // errors is an Array of errors that occurred
      },
      onComplete() {
        // this is called once your service completed running
      }
    })

    Documentation

    Principessa currently exposes a function, which returns an object (the public API) with currently only one public method execute.
    The function that is exposed currently takes no arguments, but may later accept some custom configuration.
    The execute method accepts on parameter, which configures principessa for this specific execution of your service:

    • payload: the payload corresponds to the input that your service should get. If your input contains any files that need to be downloaded first, you need to indicate them separately. See here for how the payload should be structured.
    • onRun(options): this function will be called when principessa is done preparing your options. It will extend the options you specified in the payload with the resolved assets's paths, so your service is good to go with local assets.
    • onError(errors): callback function that will be called with an array of errors that occurred during payload validation or execution of your service
    • onComplete(): callback function that will be called once your service is done processing. You can optionally return an object, that will be appended to the callback payload

    Payload format

    The payload must conform with this JSON schema:

    {
      "type": "object",
      "properties": {
        "storageProvider": {
          "enum": ["s3"]
        },
        "storageProviderConfig": {
          "type": "object"
        },
        "assets": {
          "type": "object",
          "patternProperties": {
            ".*": {
              "type": "string"
            }
          }
        },
        "options": {
          "type": "object"
        },
        "output": {
          "type": "object"
        },
        "callbackUrl": {
          "type": "string"
        }
      },
      "required": ["options"],
      "additionalProperties": false
    }

    Example:

    {
      "storageProvider": "s3",
      "storageProviderConfig": {
        "Bucket": "bucket-with-files"
      },
      "assets": {
        "inputFile1": "my-input-file.json"
      },
      "options": {
        "serviceSpecificOption123": true,
        "continueOnProblems": false,
        "outputFolder": "/output"
      },
      "output": {
        "transformedFile": "/output/my-output-file.json"
      },
      "callbackUrl": "http://scheduler.commercetools.io/${taskId}/done"
    }

    Assets

    In the assets section you should list all files that are needed as Input for your service. Every asset will be downloaded from the configured storage provider, and stored locally. Then the asset will be appended to the options object, by using the key and the resolved path of the asset. Example:

    {
      storageProvider: "s3",
      storageProviderConfig: {
        Bucket: 'your-amazon-s3-bucket'
      },
      options: {
        someOption: true
      },
      assets: {
        inputFile: 'products.csv'
      }
    }

    The onRun method would then be called with the following options, which are ready to be used by your service.

    {
      someOptions: true,
      inputFile: '/localWorkerDir/products.csv'
    }

    Options

    The options object is basically a pass-through for your service. You can put any kind of input that your worker needs here.

    Supported storage providers

    At the moment we only support Amazon S3. If you want to use it you have to configure it in the payload. You simply set the storageProvider option to s3 and provide an s3 bucket, where principessa should look for your assets.
    Example:

    {
      "storageProvider": "s3",
      "storageProviderConfig": {
        "bucket": "bucket-with-assets"
      }
    }

    Also you need to put store your credentials in environment variables:

    export AWS_ACCESS_KEY_ID=***
    export AWS_SECRET_ACCESS_KEY=***

    Output and callbackUrl

    If your service produces files as output, you can list these in the output object. They will then be uploaded to your configured storage provider, and passed to the callbackUrl in a POST request. Example: You have a product export service, that produces a csv file, named 'products.csv', and puts it in the /output folder. The following configuration would pick this file up, upload it to S3 and call the callbackUrl with a reference to the file:

    {
      "storageProvider": "s3",
      "storageProviderConfig": {
        "bucket": "bucket-with-assets"
      },
      options: {
        outputFolder: '/output'
      },
      output: {
        productsFile: 'products.csv'
      },
      callbackUrl: 'http://scheduler.commercetoools.io/jobs/<job-id>/done'
    }

    This would result in a POST request like this:

    curl
      -H "Content-Type: application/json"
      -X POST -d '{
        "productsFile":"http://aws.amazon.com/2c4950gu8n94gmx2495cm.csv"
      }'
      http://scheduler.commercetoools.io/jobs/<job-id>/done

    Keywords

    none

    Install

    npm i principessa

    DownloadsWeekly Downloads

    3

    Version

    1.5.0

    License

    MIT

    Last publish

    Collaborators

    • philippspo