chore(rest): add openapi spec to the tree

Add pre-commit hook to make sure we update the spec as we change the
 rest code.
Add another step to the CI linter to check that the spec is up to date.
(Note the linter here isn't quite right for this)

.pre-commit-config.yaml

@@ -37,4 +37,11 @@ repos:
         entry: bash -c "npm install @commitlint/config-conventional @commitlint/cli; cat $1 | npx commitlint"
         args: [$1]
         stages: [commit-msg]
+    -   id: openapi-check
+        name: OpenApi Generator
+        description: Ensures OpenApi spec is up to date
+        entry: ./scripts/openapi-check.sh
+        args: ["--changes"]
+        pass_filenames: false
+        language: system
 

Jenkinsfile

@@ -110,6 +110,7 @@ pipeline {
         sh 'nix-shell --run "cargo fmt --all -- --check"'
         sh 'nix-shell --run "cargo clippy --all-targets -- -D warnings"'
         sh 'nix-shell --run "./scripts/js-check.sh"'
+        sh 'nix-shell --run "./scripts/openapi-check.sh"'
       }
     }
     stage('test') {

control-plane/rest/openapi-specs/v0_api_spec.json

@@ -0,0 +1 @@
+{"swagger":"2.0","definitions":{"Child":{"type":"object","properties":{"rebuildProgress":{"description":"current rebuild progress (%)","type":"integer","format":"int32"},"state":{"description":"state of the child","type":"string","enum":["Unknown","Online","Degraded","Faulted"]},"uri":{"description":"uri of the child device","type":"string"}},"required":["state","uri"]},"CreateNexusBody":{"type":"object","properties":{"children":{"description":"replica can be iscsi and nvmf remote targets or a local spdk bdev\n (i.e. bdev:///name-of-the-bdev).\n\n uris to the targets we connect to","type":"array","items":{"description":"URI of a mayastor nexus child","type":"string"}},"size":{"description":"size of the device in bytes","type":"integer","format":"int64"}},"required":["children","size"]},"CreatePoolBody":{"type":"object","properties":{"disks":{"description":"disk device paths or URIs to be claimed by the pool","type":"array","items":{"type":"string"}}},"required":["disks"]},"CreateReplicaBody":{"type":"object","properties":{"share":{"description":"protocol to expose the replica over","type":"string","enum":["off","nvmf","iscsi","nbd"]},"size":{"description":"size of the replica in bytes","type":"integer","format":"int64"},"thin":{"description":"thin provisioning","type":"boolean"}},"required":["share","size","thin"]},"CreateVolumeBody":{"type":"object","properties":{"allowed_nodes":{"description":"only these nodes can be used for the replicas","type":"array","items":{"description":"ID of a mayastor node","type":"string"}},"nexuses":{"description":"number of children nexuses (ANA)","type":"integer","format":"int64"},"preferred_nexus_nodes":{"description":"preferred nodes for the nexuses","type":"array","items":{"description":"ID of a mayastor node","type":"string"}},"preferred_nodes":{"description":"preferred nodes for the replicas","type":"array","items":{"description":"ID of a mayastor node","type":"string"}},"replicas":{"description":"number of replicas per nexus","type":"integer","format":"int64"},"size":{"description":"size of the volume in bytes","type":"integer","format":"int64"}},"required":["nexuses","replicas","size"]},"JsonGeneric":{"type":"object","properties":{"inner":{}},"required":["inner"]},"Nexus":{"type":"object","properties":{"children":{"description":"array of children","type":"array","items":{"description":"Child information","type":"object","properties":{"rebuildProgress":{"description":"current rebuild progress (%)","type":"integer","format":"int32"},"state":{"description":"state of the child","type":"string","enum":["Unknown","Online","Degraded","Faulted"]},"uri":{"description":"uri of the child device","type":"string"}},"required":["state","uri"]}},"deviceUri":{"description":"URI of the device for the volume (missing if not published).\n Missing property and empty string are treated the same.","type":"string"},"node":{"description":"id of the mayastor instance","type":"string"},"rebuilds":{"description":"total number of rebuild tasks","type":"integer","format":"int32"},"size":{"description":"size of the volume in bytes","type":"integer","format":"int64"},"state":{"description":"current state of the nexus","type":"string","enum":["Unknown","Online","Degraded","Faulted"]},"uuid":{"description":"uuid of the nexus","type":"string"}},"required":["children","deviceUri","node","rebuilds","size","state","uuid"]},"Node":{"type":"object","properties":{"grpcEndpoint":{"description":"grpc_endpoint of the mayastor instance","type":"string"},"id":{"description":"id of the mayastor instance","type":"string"},"state":{"description":"deemed state of the node","type":"string","enum":["Unknown","Online","Offline"]}},"required":["grpcEndpoint","id","state"]},"Pool":{"type":"object","properties":{"capacity":{"description":"size of the pool in bytes","type":"integer","format":"int64"},"disks":{"description":"absolute disk paths claimed by the pool","type":"array","items":{"type":"string"}},"id":{"description":"id of the pool","type":"string"},"node":{"description":"id of the mayastor instance","type":"string"},"state":{"description":"current state of the pool","type":"string","enum":["Unknown","Online","Degraded","Faulted"]},"used":{"description":"used bytes from the pool","type":"integer","format":"int64"}},"required":["capacity","disks","id","node","state","used"]},"Replica":{"type":"object","properties":{"node":{"description":"id of the mayastor instance","type":"string"},"pool":{"description":"id of the pool","type":"string"},"share":{"description":"protocol used for exposing the replica","type":"string","enum":["off","nvmf","iscsi","nbd"]},"size":{"description":"size of the replica in bytes","type":"integer","format":"int64"},"thin":{"description":"thin provisioning","type":"boolean"},"uri":{"description":"uri usable by nexus to access it","type":"string"},"uuid":{"description":"uuid of the replica","type":"string"}},"required":["node","pool","share","size","thin","uri","uuid"]},"Volume":{"type":"object","properties":{"children":{"description":"array of children nexuses","type":"array","items":{"description":"Nexus information","type":"object","properties":{"children":{"description":"array of children","type":"array","items":{"description":"Child information","type":"object","properties":{"rebuildProgress":{"description":"current rebuild progress (%)","type":"integer","format":"int32"},"state":{"description":"state of the child","type":"string","enum":["Unknown","Online","Degraded","Faulted"]},"uri":{"description":"uri of the child device","type":"string"}},"required":["state","uri"]}},"deviceUri":{"description":"URI of the device for the volume (missing if not published).\n Missing property and empty string are treated the same.","type":"string"},"node":{"description":"id of the mayastor instance","type":"string"},"rebuilds":{"description":"total number of rebuild tasks","type":"integer","format":"int32"},"size":{"description":"size of the volume in bytes","type":"integer","format":"int64"},"state":{"description":"current state of the nexus","type":"string","enum":["Unknown","Online","Degraded","Faulted"]},"uuid":{"description":"uuid of the nexus","type":"string"}},"required":["children","deviceUri","node","rebuilds","size","state","uuid"]}},"size":{"description":"size of the volume in bytes","type":"integer","format":"int64"},"state":{"description":"current state of the volume","type":"string","enum":["Unknown","Online","Degraded","Faulted"]},"uuid":{"description":"name of the volume","type":"string"}},"required":["children","size","state","uuid"]}},"paths":{"/nexuses":{"get":{"responses":{"200":{"description":"OK","schema":{"type":"array","items":{"$ref":"#/definitions/Nexus"}}}},"tags":["Nexuses"]}},"/nexuses/{nexus_id}":{"get":{"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/Nexus"}}},"parameters":[{"in":"path","name":"nexus_id","required":true,"type":"string"}],"tags":["Nexuses"]},"delete":{"responses":{"200":{"description":"OK","schema":{}}},"parameters":[{"in":"path","name":"nexus_id","required":true,"type":"string"}],"tags":["Nexuses"]}},"/nexuses/{nexus_id}/children":{"get":{"responses":{"200":{"description":"OK","schema":{"type":"array","items":{"$ref":"#/definitions/Child"}}}},"parameters":[{"in":"path","name":"nexus_id","required":true,"type":"string"}],"tags":["Children"]}},"/nexuses/{nexus_id}/children/{child_id:.*}":{"get":{"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/Child"}}},"parameters":[{"in":"path","name":"nexus_id","required":true,"type":"string"},{"in":"path","name":"child_id:.*","required":true,"type":"string"}],"tags":["Children"]},"put":{"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/Child"}}},"parameters":[{"in":"path","name":"nexus_id","required":true,"type":"string"},{"in":"path","name":"child_id:.*","required":true,"type":"string"}],"tags":["Children"]},"delete":{"responses":{"200":{"description":"OK","schema":{}}},"parameters":[{"in":"path","name":"nexus_id","required":true,"type":"string"},{"in":"path","name":"child_id:.*","required":true,"type":"string"}],"tags":["Children"]}},"/nodes":{"get":{"responses":{"200":{"description":"OK","schema":{"type":"array","items":{"$ref":"#/definitions/Node"}}}},"tags":["Nodes"]}},"/nodes/{id}":{"get":{"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/Node"}}},"parameters":[{"in":"path","name":"id","required":true,"type":"string"}],"tags":["Nodes"]}},"/nodes/{id}/nexuses":{"get":{"responses":{"200":{"description":"OK","schema":{"type":"array","items":{"$ref":"#/definitions/Nexus"}}}},"parameters":[{"in":"path","name":"id","required":true,"type":"string"}],"tags":["Nexuses"]}},"/nodes/{id}/pools":{"get":{"responses":{"200":{"description":"OK","schema":{"type":"array","items":{"$ref":"#/definitions/Pool"}}}},"parameters":[{"in":"path","name":"id","required":true,"type":"string"}],"tags":["Pools"]}},"/nodes/{id}/replicas":{"get":{"responses":{"200":{"description":"OK","schema":{"type":"array","items":{"$ref":"#/definitions/Replica"}}}},"parameters":[{"in":"path","name":"id","required":true,"type":"string"}],"tags":["Replicas"]}},"/nodes/{node_id}/nexuses/{nexus_id}":{"get":{"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/Nexus"}}},"parameters":[{"in":"path","name":"node_id","required":true,"type":"string"},{"in":"path","name":"nexus_id","required":true,"type":"string"}],"tags":["Nexuses"]},"put":{"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/Nexus"}}},"parameters":[{"in":"path","name":"node_id","required":true,"type":"string"},{"in":"path","name":"nexus_id","required":true,"type":"string"},{"in":"body","name":"body","required":true,"schema":{"$ref":"#/definitions/CreateNexusBody"}}],"tags":["Nexuses"]},"delete":{"responses":{"200":{"description":"OK","schema":{}}},"parameters":[{"in":"path","name":"node_id","required":true,"type":"string"},{"in":"path","name":"nexus_id","required":true,"type":"string"}],"tags":["Nexuses"]}},"/nodes/{node_id}/nexuses/{nexus_id}/children":{"get":{"responses":{"200":{"description":"OK","schema":{"type":"array","items":{"$ref":"#/definitions/Child"}}}},"parameters":[{"in":"path","name":"node_id","required":true,"type":"string"},{"in":"path","name":"nexus_id","required":true,"type":"string"}],"tags":["Children"]}},"/nodes/{node_id}/nexuses/{nexus_id}/children/{child_id:.*}":{"get":{"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/Child"}}},"parameters":[{"in":"path","name":"node_id","required":true,"type":"string"},{"in":"path","name":"nexus_id","required":true,"type":"string"},{"in":"path","name":"child_id:.*","required":true,"type":"string"}],"tags":["Children"]},"put":{"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/Child"}}},"parameters":[{"in":"path","name":"node_id","required":true,"type":"string"},{"in":"path","name":"nexus_id","required":true,"type":"string"},{"in":"path","name":"child_id:.*","required":true,"type":"string"}],"tags":["Children"]},"delete":{"responses":{"200":{"description":"OK","schema":{}}},"parameters":[{"in":"path","name":"node_id","required":true,"type":"string"},{"in":"path","name":"nexus_id","required":true,"type":"string"},{"in":"path","name":"child_id:.*","required":true,"type":"string"}],"tags":["Children"]}},"/nodes/{node_id}/nexuses/{nexus_id}/share":{"delete":{"responses":{"200":{"description":"OK","schema":{}}},"parameters":[{"in":"path","name":"node_id","required":true,"type":"string"},{"in":"path","name":"nexus_id","required":true,"type":"string"}],"tags":["Nexuses"]}},"/nodes/{node_id}/nexuses/{nexus_id}/share/{protocol}":{"put":{"responses":{"200":{"description":"OK","schema":{"type":"string"}}},"parameters":[{"in":"path","name":"node_id","required":true,"type":"string"},{"in":"path","name":"nexus_id","required":true,"type":"string"},{"in":"path","name":"protocol","required":true,"type":"string","enum":["off","nvmf","iscsi","nbd"]}],"tags":["Nexuses"]}},"/nodes/{node_id}/pools/{pool_id}":{"get":{"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/Pool"}}},"parameters":[{"in":"path","name":"node_id","required":true,"type":"string"},{"in":"path","name":"pool_id","required":true,"type":"string"}],"tags":["Pools"]},"put":{"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/Pool"}}},"parameters":[{"in":"path","name":"node_id","required":true,"type":"string"},{"in":"path","name":"pool_id","required":true,"type":"string"},{"in":"body","name":"body","required":true,"schema":{"$ref":"#/definitions/CreatePoolBody"}}],"tags":["Pools"]},"delete":{"responses":{"200":{"description":"OK","schema":{}}},"parameters":[{"in":"path","name":"node_id","required":true,"type":"string"},{"in":"path","name":"pool_id","required":true,"type":"string"}],"tags":["Pools"]}},"/nodes/{node_id}/pools/{pool_id}/replicas":{"get":{"responses":{"200":{"description":"OK","schema":{"type":"array","items":{"$ref":"#/definitions/Replica"}}}},"parameters":[{"in":"path","name":"node_id","required":true,"type":"string"},{"in":"path","name":"pool_id","required":true,"type":"string"}],"tags":["Replicas"]}},"/nodes/{node_id}/pools/{pool_id}/replicas/{replica_id}":{"get":{"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/Replica"}}},"parameters":[{"in":"path","name":"node_id","required":true,"type":"string"},{"in":"path","name":"pool_id","required":true,"type":"string"},{"in":"path","name":"replica_id","required":true,"type":"string"}],"tags":["Replicas"]},"put":{"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/Replica"}}},"parameters":[{"in":"path","name":"node_id","required":true,"type":"string"},{"in":"path","name":"pool_id","required":true,"type":"string"},{"in":"path","name":"replica_id","required":true,"type":"string"},{"in":"body","name":"body","required":true,"schema":{"$ref":"#/definitions/CreateReplicaBody"}}],"tags":["Replicas"]},"delete":{"responses":{"200":{"description":"OK","schema":{}}},"parameters":[{"in":"path","name":"node_id","required":true,"type":"string"},{"in":"path","name":"pool_id","required":true,"type":"string"},{"in":"path","name":"replica_id","required":true,"type":"string"}],"tags":["Replicas"]}},"/nodes/{node_id}/pools/{pool_id}/replicas/{replica_id}/share":{"delete":{"responses":{"200":{"description":"OK","schema":{}}},"parameters":[{"in":"path","name":"node_id","required":true,"type":"string"},{"in":"path","name":"pool_id","required":true,"type":"string"},{"in":"path","name":"replica_id","required":true,"type":"string"}],"tags":["Replicas"]}},"/nodes/{node_id}/pools/{pool_id}/replicas/{replica_id}/share/{protocol}":{"put":{"responses":{"200":{"description":"OK","schema":{"type":"string"}}},"parameters":[{"in":"path","name":"node_id","required":true,"type":"string"},{"in":"path","name":"pool_id","required":true,"type":"string"},{"in":"path","name":"replica_id","required":true,"type":"string"},{"in":"path","name":"protocol","required":true,"type":"string","enum":["off","nvmf","iscsi","nbd"]}],"tags":["Replicas"]}},"/nodes/{node_id}/volumes":{"get":{"responses":{"200":{"description":"OK","schema":{"type":"array","items":{"$ref":"#/definitions/Volume"}}}},"parameters":[{"in":"path","name":"node_id","required":true,"type":"string"}],"tags":["Volumes"]}},"/nodes/{node_id}/volumes/{volume_id}":{"get":{"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/Volume"}}},"parameters":[{"in":"path","name":"node_id","required":true,"type":"string"},{"in":"path","name":"volume_id","required":true,"type":"string"}],"tags":["Volumes"]}},"/nodes/{node}/jsongrpc/{method}":{"put":{"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/JsonGeneric"}}},"parameters":[{"in":"path","name":"node","required":true,"type":"string"},{"in":"path","name":"method","required":true,"type":"string"},{"in":"body","name":"body","required":true,"schema":{"$ref":"#/definitions/JsonGeneric"}}],"tags":["JsonGrpc"]}},"/pools":{"get":{"responses":{"200":{"description":"OK","schema":{"type":"array","items":{"$ref":"#/definitions/Pool"}}}},"tags":["Pools"]}},"/pools/{id}":{"get":{"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/Pool"}}},"parameters":[{"in":"path","name":"id","required":true,"type":"string"}],"tags":["Pools"]}},"/pools/{pool_id}":{"delete":{"responses":{"200":{"description":"OK","schema":{}}},"parameters":[{"in":"path","name":"pool_id","required":true,"type":"string"}],"tags":["Pools"]}},"/pools/{pool_id}/replicas/{replica_id}":{"put":{"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/Replica"}}},"parameters":[{"in":"path","name":"pool_id","required":true,"type":"string"},{"in":"path","name":"replica_id","required":true,"type":"string"},{"in":"body","name":"body","required":true,"schema":{"$ref":"#/definitions/CreateReplicaBody"}}],"tags":["Replicas"]},"delete":{"responses":{"200":{"description":"OK","schema":{}}},"parameters":[{"in":"path","name":"pool_id","required":true,"type":"string"},{"in":"path","name":"replica_id","required":true,"type":"string"}],"tags":["Replicas"]}},"/pools/{pool_id}/replicas/{replica_id}/share":{"delete":{"responses":{"200":{"description":"OK","schema":{}}},"parameters":[{"in":"path","name":"pool_id","required":true,"type":"string"},{"in":"path","name":"replica_id","required":true,"type":"string"}],"tags":["Replicas"]}},"/pools/{pool_id}/replicas/{replica_id}/share/{protocol}":{"put":{"responses":{"200":{"description":"OK","schema":{"type":"string"}}},"parameters":[{"in":"path","name":"pool_id","required":true,"type":"string"},{"in":"path","name":"replica_id","required":true,"type":"string"},{"in":"path","name":"protocol","required":true,"type":"string","enum":["off","nvmf","iscsi","nbd"]}],"tags":["Replicas"]}},"/replicas":{"get":{"responses":{"200":{"description":"OK","schema":{"type":"array","items":{"$ref":"#/definitions/Replica"}}}},"tags":["Replicas"]}},"/replicas/{id}":{"get":{"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/Replica"}}},"parameters":[{"in":"path","name":"id","required":true,"type":"string"}],"tags":["Replicas"]}},"/volumes":{"get":{"responses":{"200":{"description":"OK","schema":{"type":"array","items":{"$ref":"#/definitions/Volume"}}}},"tags":["Volumes"]}},"/volumes/{volume_id}":{"get":{"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/Volume"}}},"parameters":[{"in":"path","name":"volume_id","required":true,"type":"string"}],"tags":["Volumes"]},"put":{"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/Volume"}}},"parameters":[{"in":"path","name":"volume_id","required":true,"type":"string"},{"in":"body","name":"body","required":true,"schema":{"$ref":"#/definitions/CreateVolumeBody"}}],"tags":["Volumes"]},"delete":{"responses":{"200":{"description":"OK","schema":{}}},"parameters":[{"in":"path","name":"volume_id","required":true,"type":"string"}],"tags":["Volumes"]}}},"basePath":"/v0","info":{"version":"v0","title":"Mayastor RESTful API"}}