Unofficial Rust crate for accessing Xen Orchestra through its API

Unofficial Rust crate for accessing

xo-api-client

Xen Orchestra through its API

Under development

The library is still in early development, please do not use in production. The API is nowhere near complete and only covers a very small fraction of XO's api. Lots of things might get changed and/or added in breaking ways at any time.

Async Runtime

This library uses the tokio v1 runtime

Example

Example of listing all VMs with the tag Test

use std::collections::BTreeMap;
use xo_api_client::{credentials::EmailAndPassword, Client, Vm, VmId};

// We dont care about any of the data under the "other" attribute
// in this example
#[derive(serde::Deserialize)]
struct OtherInfo {}

impl xo_api_client::vm::OtherInfo for OtherInfo {}

#[tokio::main]
async fn main() {
    let url = "ws://localhost:8080/api/";
    let email = String::from("[email protected]");
    let password = String::from("admin");

    let con = Client::connect(url)
        .await
        .expect("Failed to connect to server");
        
    con.sign_in(EmailAndPassword { email, password })
        .await
        .expect("Failed to sign in");

    let all_vms: BTreeMap<VmId, Vm<OtherInfo>> =
        con.get_vms(None, None).await.expect("Failed to list VMs");

    let test_vms = all_vms
        .iter()
        .filter(|(_id, vm)| vm.tags.iter().any(|tag| tag == "Test"));

    println!("All VMs with the tag 'Test':");
    for (id, vm) in test_vms {
        println!("ID: {:?}, Name: {}", id, vm.name_label);
    }
}

License

xo-api-client is distributed under the terms of both the MIT license and the Apache License (Version 2.0).

See LICENSE-APACHE, and LICENSE-MIT for details.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in xo-api-client by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Issues

Collection of the latest Issues

usbalbin

usbalbin

0

Add a Host type to interact with hosts. Some of the procedures available for hosts([see all_procedures.md](https://github.com/usbalbin/xo-api-client/blob/master/all_procedures.md for more)):

  • host.emergencyShutdownHost host=<string> suspend all VMs and shutdown host
  • host.restart id=<string> [force=<boolean>] restart the host
  • host.setMaintenanceMode id=<string> maintenance=<boolean> manage the maintenance mode
  • host.start id=<string> start the host
  • host.stats host=<string> [granularity=<string>] returns statistic of the host`
  • host.stop id=<string> stop the host
usbalbin

usbalbin

1

There are quite a lot of examples of things in the types sent by xo-server that might make sense in javascript/json but less so in rust. To get out the most out of rusts strong type system some translations might be needed.

I believe there are atleast three categories of types:

  • stringly -> strict(er) types. One such example would be ip addresses. In the json object they are simply a string. In rust something like a std::net::IpAddr might make more sense. However, due to not all strings being valid IpAddr'es there is a dilemma - Do we know for a fact that xo-server always gives us valid ip addresses?
  • null/undefined -> empty map there are several examples in where xo-server sometimes uses null/undefined for a field and other times an object for that same field. This can be modeled in rust for example by using Option<HashMap<...>>. However it is not clear to me whether the distinction between {}, null and undefined in those cases is of importance. Perhaps something like the address field of Vm could be represented as a plain HasMap not wrapped in any option. This would make it more streamlined to work with. However this is technically a lossy conversion and because of this any serialization again could look different from the original.

TODO describe better and add more cases

usbalbin

usbalbin

1

What we get from xo-server might look something like this for address value in a vm object

Pfsense VM:

Windows VM


TODO:

  • Figure out what different values are possible
    • Judging from the data above, one might guess that the key is on something like on the form: $network_card_id/{ipv4|ipv6}/$network_port_id or something similar. Check the source
  • Decide on a fitting rust type structure to represent addresses
Versions

Find the latest versions by id

v0.1.1 - Nov 06, 2021

implement Hash for id types like VmId and similar. This is required for using id types as key in HashMaps.

implement From<String> for Token.

What's Changed

Full Changelog: https://github.com/usbalbin/xo-api-client/compare/v0.1.0...v0.1.1

v0.1.0 - Nov 04, 2021

Breaking

Moves procedure methods to their own modules under api:

  • Client::sign_in => Client.session.sign_in
  • Client::create_token => Client.token::create
  • Client::restart_nonblocking => Client.vm.restart_nonblocking
  • Client::snapshot => Client.vm.snapshot
  • Client::revert_snapshot => Client.vm.revert
  • Client::delete_snapshot => Client.vm.delete
  • Client.get_all_objects => Client.xo.get_all_objects
  • Client.get_vms => Client.xo.get_vms
  • Client.get_snapshots => Client.xo.get_snapshots

Move most functions and types to relevant api modules

v0.0.5 - Oct 18, 2021

Update jsonrpsee to 0.4

v0.0.4 - Sep 25, 2021

Update possibly insecure tokio

v0.0.3 - Aug 13, 2021

Updated jsonrpsee_ws_client from 0.2 to 0.3

v0.0.2 - Jun 24, 2021

Breaking changes

Changes from

to

Change broken Snapshot type to


More derives

This implements

Debug for ObjectType serde::Serialize for VmId and SnapshotId PartialEq and Eq for PowerState

Tests

This adds some tests which deserialize different example objects into instances of Vm or Snapshot and tests its methods.

v0.0.1 - Jun 05, 2021

This is the very first release!

The library is still in early development, please do not use in production. The API is nowhere near complete and only covers a very small fraction of XO's api. Lots of things might get changed and/or added in breaking ways at any time.

Information - Updated May 25, 2022

Stars: 0
Forks: 0
Issues: 5

serde-json for no_std programs

MIT license (LICENSE-MIT or

serde-json for no_std programs

macOS/iOS Security framework for Rust

MIT license (LICENSE-MIT or

macOS/iOS Security framework for Rust

OpenGliderNetwork client for Rust based on actix

MIT license (LICENSE-MIT or

OpenGliderNetwork client for Rust based on actix

A video game for programmers set in space

MIT license (LICENSE-MIT or

A video game for programmers set in space

Simple SQL migration manager for your project

MIT license (LICENSE-MIT or

Simple SQL migration manager for your project

TODO_README_DESCRIPTION

(LICENSE-MIT or Semantic Versioning 2

TODO_README_DESCRIPTION

CBOR Event library

MIT license (LICENSE-MIT or

CBOR Event library

HAL for the STM32WB55 family of microcontrollers

MIT license (LICENSE-MIT or

HAL for the STM32WB55 family of microcontrollers
CLI

123

write licenses to stdout

Write a license to standard output given its SPDX ID

write licenses to stdout

A simple easy to use wrapper around Ctrl-C signal

MIT license (LICENSE-MIT or

A simple easy to use wrapper around Ctrl-C signal
Facebook Instagram Twitter GitHub Dribbble
Privacy