feat(rust): add an HTTP/JSON API to DASD operations

[imobachgs]

Trello: https://trello.com/c/2LC8JEZR/3743-8-agama-adapt-dasd-configuration-to-current-architecture

This PR is the first step to bring back support for DASD devices on s390x architectures. It includes:

• Extending the HTTP API to expose DASD devices and formatting jobs.
• Adding DASD-related events (adding, updating and changing DASD devices and format progress).

After some discussion, we decided to retain the original intention of the D-Bus API at HTTP level.

Examples

This section contains a few examples you can use to explore the API. For the ones using curl, it is required to have a headers.txt file containing the credentials (similar to the following example, but replacing TOKEN with your actual token):

Content-Type: application/json
Authorization: Bearer TOKEN

DASD operations

Remember that the -k disables the SSL certificate checking.

Probing for DASD devices

curl -k -H @headers.txt -X POST https://$AGAMA_SERVER/api/storage/dasd/probe

Listing DASD devices

$ curl -k --silent -H @headers.txt -X GET https://$AGAMA_SERVER/api/storage/dasd/devices | jq
[
  {
    "id": "0.0.0160",
    "enabled": true,
    "device_name": "dasda",
    "formatted": true,
    "diag": false,
    "status": "active",
    "device_type": "ECKD",
    "access_type": "rw",
    "partition_info": ""
  }
]

Enabling DASD devices

[!NOTE]
We might consider using PATCH or even POST for enabling, disabling, setting diag and formatting the device.

$ curl -k -H @headers.txt -X POST https://$AGAMA_SERVER/api/storage/dasd/enable \
  -d '{"devices": ["0.0.0160"]}'

Disabling devices

$ curl -k -H @headers.txt -X POST https://$AGAMA_SERVER/api/storage/dasd/disable \
  -d '{"devices": ["0.0.0160"]}'

Setting the DIAG attribute

$ curl -k -H @headers.txt -X PUT https://$AGAMA_SERVER/api/storage/dasd/diag \
  -d '{"devices": ["0.0.0160"], "diag": true}'

Formatting devices

$ curl -k -H @headers.txt -X PUT https://$AGAMA_SERVER/api/storage/dasd/format \
  -d '{"devices": ["0.0.0160"]}'

Jobs operation

Listing jobs

$ curl -k -H @headers.txt -X GET https://$AGAMA_SERVER/api/storage/jobs | jq
[
  {
    "id": "/org/opensuse/Agama/Storage1/jobs/3",
    "running": false,
    "exit_code": 0
  },
  {
    "id": "/org/opensuse/Agama/Storage1/jobs/2",
    "running": false,
    "exit_code": 0
  }
]

Events

The PR adds the following events:

• DASDDeviceAdded, DASDDeviceChaned and DASDDeviceRemoved.
• JobAdded, JobChanged and JobRemoved.
• DASDFormatProgress.

[!WARNING]
The Finished signal of the org.opensuse.Agama.Storage1.Job is not handled.

Let's see a few examples:

Formatting progress

{
  "type": "DASDFormatJobChanged",
  "job_id": "/org/opensuse/Agama/Storage1/jobs/9",
  "total": 30050,
  "step": 30050,
  "done": true
}

DASD device detected

{
  "type": "DASDDeviceAdded",
  "device": {
    "id": "0.0.0160",
    "enabled": true,
    "device_name": "dasda",
    "formatted": false,
    "diag": false,
    "status": "no_format",
    "device_type": "ECKD",
    "access_type": "rw",
    "partition_info": ""
  }
}

DASD device changes

{
  "type": "DASDDeviceChanged",
  "device": {
    "id": "0.0.0160",
    "enabled": true,
    "device_name": "dasda",
    "formatted": false,
    "diag": false,
    "status": "no_format",
    "device_type": "ECKD",
    "access_type": "rw",
    "partition_info": ""
  }
}

A notes about signals

We have discussed whether we are abusing standard D-Bus signals a bit. For instance, we rely heavily on PropertiesChanged, InterfacesAdded, InterfacesRemoved, etc., even for meaningful and important system events. Then, the client code needs to figure out what those signals actually mean. Also, unless you use a proxy (and that's not always possible), you cannot rely on the type checking that the introspection offers.

Of course, that's out of the scope of this pull request.

Code repetition

As you might notice, there is quite some repetitive code. At this point, I just wanted to have some working code. We can reduce the repetition later. Improving our signals would help reduce the amount of code on the client side.

[coveralls]

coverage: 70.597% (-0.7%) from 71.319%
when pulling a226fec on http-dasd
into 55fabd7 on master.

[imobachgs]

Some of the fields in this struct (status, device_type and/or access_type) might deserve an enum.

[jreidinger]

btw resulting json is not consistent with others. I think agreemend is snakeCase...so let me change it to #[serde(rename_all = "camelCase")]

[jreidinger]

API looks strange, it allows formating multiple DASDs but it return only one path for job.

[imobachgs]

That's what I deduced from https://github.com/openSUSE/agama/blob/master/service/lib/agama/dbus/storage/interfaces/dasd_manager.rb#L139.

[teclator]

there is only one job, that is ok, but then we need to check the status for each device, I think the missing part is the job Summary call on formatProgress callback.

https://github.com/openSUSE/agama/blob/master/web/src/client/storage.js#L891

[teclator]

I say nothing, it already uses the Summary but the DASD path is not sent at all...

see ... https://github.com/openSUSE/agama/pull/1532/files#diff-481b9b86ced79110f138995e6097a0f0cde62016924c72f1c5c6397940566654R210
and ... https://github.com/openSUSE/agama/pull/1532/files#diff-481b9b86ced79110f138995e6097a0f0cde62016924c72f1c5c6397940566654R220

[jreidinger]

good, I recheck that it affects only dasd format event. So it is safe.