[ovirt-devel] [VDSM][JSON RPC] new vdsClient?

[Saggi Mizrahi]

First let me say kudos on kickstarting the discussion
having a CLI client is essential for admins and (as the
current CLI can show us) it's important to get it right.

We currently have a Python client used in testing.
It's efficient and low level enough to be used by
any consumer of the VDSM API. It can handle large
number of connections to VDSMs and you can use it
in sync\async\cooperative situations.

There might be a place to give something a bit simpler
to set up for testing and simple scripts. I have WIP
patches locally, I'll send them when I get a chance.


As for a CLI.

There are important things to consider:
1. The client should be independent of the API.
   This is an admin tool that can't be targeted to a
   single version of VDSM.

2. Above the JSON-RPC level there is there concept of the
   queues. Specifically you have to know the queue you
   want to push you messages to and the queue where the responses
   will be returned at.

   We also need to keep in mind that VDSM is going to be split up
   to multiple subsystems with their own queues. This means the
   cli will need that to be specified.

   There will be a some sort of convention on how queues are named.
   But until that is done we can't really release a cli tool that we
   can support.

   Also keep in minds that queues are not broadcast (notifications are)
   which means that if there is an engine connected it might pop the
   response from the queue before the CLI would.

   We do intend to introduce a header "X-rpc-response-queue" to solve this
   but we don't know if we will manage to do it by 3.6.
  
3. Starting in 3.6 and forward a lot of operations will slowly move
   from request\response to a more advanced model of asynchronous
   messaging. This means that copyImage() will just return if the copy
   was started and not if it's done. Progress information and
   errors\etc will be sent as notifications and will be polled outside
   the scope of the request itself. The CLI will obviously be limited to
   polling.


The current model I have in mind is:

vdsm-cli [options] <subsystem> [<method name> [argument, ...]]

If no method name specified the program will read raw json requests
from stdin and push raw responses to stdout.

-a --address      the remote address when omitted uses the
                  environment variable VDSM_CLI_ADDRESS. if
                  both are omitted tries to connect to the
                  local broker in /var/run/vsdm/broker.socket .
                  eg. stomp://example.com stmop+ssl://foo.com
-r --raw          print the raw json result.
-n --nowait       don't wait for a response.

--------------------------------------------

Which will return either the result or error fields (only one of them
should be returned). You would differentiate using the return code.

Unless the user uses --raw the response should be returned in
a format similar to yaml:

key: value
list_key: a, b, c, d
map_key:
   key2: value
   key3: value
   text_with_multiple_lines:
       this text has multiple lines
       in-did it does
   another_key: 231

Having the stdin\stdout option will solve most cases where
users want to send multiple requests but don't want to use
python and don't want to implement STOMP\JSON_RPC.
(even in shellscript [1])


For developers we are working on a sugary wrapper around the low level
Python API so you could use IPython to debug VSDM. I want to encourage
developers to write python tests instead of testing using the CLI.
It should be out in the next few days.

```
import vdsm.client

client = client.ClientFactory("stomp://address:port/_local/vdsm/requests")
client.doX(args)
cb = client.doX_async(args)
cb.wait()
client.waitForEvent("event.*.mask")
```

[1] http://www.rolandfg.net/2014/07/29/json-commandline-processor/
----- Original Message -----
> From: "Francesco Romani" <fromani at redhat.com>
> To: devel at ovirt.org
> Sent: Friday, November 14, 2014 6:44:52 PM
> Subject: Re: [ovirt-devel] [VDSM][JSON RPC] new vdsClient?
> 
> ----- Original Message -----
> > From: "Francesco Romani" <fromani at redhat.com>
> > To: devel at ovirt.org
> > Sent: Friday, November 14, 2014 5:34:57 PM
> > Subject: [ovirt-devel] [VDSM][JSON RPC] new vdsClient?
> 
> 
> [...]
> > At least, we can to put together a wishlist for a new vdsClient and add it
> > to
> > the wiki.
> > 
> > My one, so far:
> [...]
> 
> Hit 'send' too early:
> 
> * client library package: we should have a program-friendly python package to
> access
>   VDSM, in order to make it more testable, and vdsClient should be a thin
>   layer around
>   that
> * schema-based: the package/tool should be given a schema file, and determine
> the API
>   from that.
> * JSON for input: I's like to open logs, grab a line including a command and
> feed
>   vdsClient with the very same line
> * JSON for output as well (seems nice, no real use case in mind)
> 
> --
> Francesco Romani
> RedHat Engineering Virtualization R & D
> Phone: 8261328
> IRC: fromani
> _______________________________________________
> Devel mailing list
> Devel at ovirt.org
> http://lists.ovirt.org/mailman/listinfo/devel
>