pfurl 2.3.0.1

(Python) Path-File URL comms

Table of Contents

• Overview

  • pfurl

• Installation

  • Python Virtual Environment

  • Using the fnndsc/pfurl container

• Usage

• Examples

Overview

This repository provides a curl-like client tool that is also able to perform simple file/directory functions (such as zip/unzip) suitable for remote http transmission:

• pfurl: a tool to transfer data using HTTP (similar to curl);

pfurl

pfurl is part of the pf family of utilities, and used as components of the ChRIS Research Integration System.

In the simplest sense, pfurl is a wrapper about pycurl, used to send http-based messages to remote services (typically pman and pfioh). In addition to curl-type http communication, pfurl also provides some basic file-system services: the ability to zip directories and transmit this to a remote service.

Various authentication options for verifying identify with the remote service are also available.

Installation

Installation is relatively straightforward, and we recommend using either python virtual environments or docker.

Python Virtual Environment

On Ubuntu, install the Python virtual environment creator

sudo apt install virtualenv virtualenvwrapper python3-tk

Then, create a directory for your virtual environments e.g.:

mkdir ~/python-envs

You might want to add to your .bashrc file these two lines:

export WORKON_HOME=~/python-envs
source /usr/local/bin/virtualenvwrapper.sh

Then you can source your .bashrc and create a new Python3 virtual environment:

source .bashrc
mkvirtualenv --python=python3 chris_env

To activate or “enter” the virtual env:

workon python_env

To deactivate virtual env:

deactivate

Using the fnndsc/pfurl container

The easiest option however, is to just use the fnndsc/pfurl container image.

docker pull fnndsc/pfurl

and then run

docker run --rm --name pfurl fnndsc/pfurl   \
           --VERB POST --raw                \
           --http localhost:5055/api/v1/cmd \
           --httpResponseBodyParse --msg '
           {
                "someJSONmessage": "Whatever"
           }
           '

where the msg contains JSON syntax instructions of what to perform.

Usage

For the most up-to-date usage of pfurl, consult the pfurl wiki page.

ARGS

    [--verb <RESTVERB>]
    The REST verb to use for the remote service.

    [--http <IP>:<port>]
    The address of the remote service.

    [--httpProxy [<proto>://]<IP>[:<port>]]
    If specified, instruct ``pfurl`` to use the proxy as specified.
    Currently, only 'http' is supported. Valid values for this flag
    include, for example:

        --httProxy http://proxy.host.org:1234

        --httpProxy proxy.host.org:1234

    [--jsonwrapper <outerMsgJSONwrapper>]
    An optional outer wrapper for the JSON payload.

    [--quiet]
    If specified, only echo the final JSON payload returned
    from remote server.

    [--raw]
    If specified, do not wrap return data from remote call in a
    JSON wrapper.

    [--oneShot]
    If specified, transmit a shutdown control sequence to remote server
    after communicating. This of course only works for services that
    understand the shutdown protocol.

    [--man <help>]
    Provide detailed help on various topics.

    [-x|--desc]
    Provide an overview help page.

    [-y|--synopsis]
    Provide a synopsis help summary.

    [--content-type <type>]
    Curl content-type descriptor.

    [--jsonpprintindent <indent>]
    If specified, print return JSON payload from remote service using
    <indent> indentation.

    [--unverifiedCerts]
    If specified, allows transmission of https requests with self signed SSL
    certificates.

    [--authToken <token>]
    A token to transmit with an http request. Note, you if you set an
    --authToken, then you should NOT also set an --auth.

    [--auth <user>:<passwd>]
    A user name and password authentication string.

    [--version]
    Print internal version number and exit.

    [-v|--verbosity <level>]
    Set the verbosity level. "0" typically means no/minimal output. Allows for
    more fine tuned output control as opposed to '--quiet' that effectively
    silences everything.

    --msg <JSONpayload>
    The actual JSON formatted payload to transmit to remote service.

Examples

Say ‘hello’ to a pfcon service listening on the localhost at port 5005:

pfurl                                                   \\
    --verb POST --raw                                   \\
    --http 127.0.0.1:5005/api/v1/cmd                     \\
    --jsonwrapper 'payload'                             \\
    --msg                                               \\
        '{  "action": "hello",
                "meta": {
                        "askAbout":     "sysinfo",
                        "echoBack":     "Hi there!"
                }
        }' --quiet --jsonpprintindent 4

and print response “prettily” using an indent of 4.