import proxmox-protocol crate
This is supposed to contain only the parts necessary to communicate with the server via the proxmox backup protocol. (Including the chunker, which is currently `include!()`d from the main crate. Signed-off-by: Wolfgang Bumiller <w.bumiller@proxmox.com>
This commit is contained in:
Wolfgang Bumiller
403
proxmox-protocol/src/c_client.rs
Normal file
403
proxmox-protocol/src/c_client.rs
Normal file
@ -0,0 +1,403 @@
|
||||
//! For the C API we need to provide a `Client` compatible with C. In rust `Client` takes a
|
||||
//! `T: io::Read + io::Write`, so we need to provide a way for C to provide callbacks to us to
|
||||
//! implement this.
|
||||
|
||||
use std::ffi::{CStr, CString};
|
||||
use std::io;
|
||||
use std::os::raw::{c_char, c_int, c_ulong, c_void};
|
||||
|
||||
use failure::{bail, format_err, Error};
|
||||
|
||||
/// Read callback. The first parameter is the `opaque` parameter passed to `proxmox_backup_new`,
|
||||
/// the rest are the usual read function parameters. This should return the number of bytes
|
||||
/// actually read, zero on EOF, or a negative `errno` value on error (eg. `-EAGAIN`).
|
||||
pub type ReadFn = extern "C" fn(opaque: *mut c_void, buf: *mut u8, size: u64) -> i64;
|
||||
|
||||
/// Write callback. The first parameter is the `opaque` parameter passed to `proxmox_backup_new`,
|
||||
/// the rest are the usual write function parameters. This should return the number of bytes
|
||||
/// actually written, or a negative `errno` value on error (eg. `-EAGAIN`).
|
||||
pub type WriteFn = extern "C" fn(opaque: *mut c_void, buf: *const u8, size: u64) -> i64;
|
||||
|
||||
/// Stores the external C callbacks for communicating with the protocol socket.
|
||||
struct CApiSocket {
|
||||
opaque: *mut c_void,
|
||||
read: ReadFn,
|
||||
write: WriteFn,
|
||||
}
|
||||
|
||||
/// A client instance using C callbacks for reading from and writing to the protocol socket.
|
||||
pub struct CClient {
|
||||
client: crate::Client<CApiSocket>,
|
||||
error: Option<CString>,
|
||||
upload: Option<(*const u8, usize)>,
|
||||
}
|
||||
|
||||
impl CClient {
|
||||
fn set_error(&mut self, err: Error) -> c_int {
|
||||
self.error = Some(match CString::new(err.to_string()) {
|
||||
Ok(cs) => cs,
|
||||
Err(_) => CString::new("<bad bytes in error string>").unwrap(),
|
||||
});
|
||||
-1
|
||||
}
|
||||
|
||||
#[inline(always)]
|
||||
fn bool_result(&mut self, res: Result<bool, Error>) -> c_int {
|
||||
match res {
|
||||
Ok(false) => 0,
|
||||
Ok(true) => 1,
|
||||
Err(e) => self.set_error(e),
|
||||
}
|
||||
}
|
||||
|
||||
#[inline(always)]
|
||||
fn bool_call<F>(&mut self, func: F) -> c_int
|
||||
where
|
||||
F: FnOnce(&mut crate::Client<CApiSocket>) -> Result<bool, Error>,
|
||||
{
|
||||
let res = func(&mut self.client);
|
||||
self.bool_result(res)
|
||||
}
|
||||
|
||||
#[inline(always)]
|
||||
fn int_call<F>(&mut self, func: F) -> c_int
|
||||
where
|
||||
F: FnOnce(&mut crate::Client<CApiSocket>) -> Result<c_int, Error>,
|
||||
{
|
||||
match func(&mut self.client) {
|
||||
Ok(v) => v,
|
||||
Err(e) => self.set_error(e.into()),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl io::Read for CApiSocket {
|
||||
fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
|
||||
let rc = (self.read)(self.opaque, buf.as_mut_ptr(), buf.len() as u64);
|
||||
if rc < 0 {
|
||||
Err(io::Error::from_raw_os_error((-rc) as i32))
|
||||
} else {
|
||||
Ok(rc as usize)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl io::Write for CApiSocket {
|
||||
fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
|
||||
let rc = (self.write)(self.opaque, buf.as_ptr(), buf.len() as u64);
|
||||
if rc < 0 {
|
||||
Err(io::Error::from_raw_os_error((-rc) as i32))
|
||||
} else {
|
||||
Ok(rc as usize)
|
||||
}
|
||||
}
|
||||
|
||||
fn flush(&mut self) -> io::Result<()> {
|
||||
Ok(())
|
||||
}
|
||||
}
|
||||
|
||||
/// Creates a new instance of a backup protocol client.
|
||||
///
|
||||
/// # Arguments
|
||||
///
|
||||
/// * `opaque` - An opaque pointer passed to the two provided callback methods.
|
||||
/// * `read` - The read callback.
|
||||
/// * `write` - The write callback.
|
||||
#[no_mangle]
|
||||
pub extern "C" fn proxmox_backup_new(
|
||||
opaque: *mut c_void,
|
||||
read: ReadFn,
|
||||
write: WriteFn,
|
||||
) -> *mut CClient {
|
||||
Box::leak(Box::new(CClient {
|
||||
client: crate::Client::new(CApiSocket {
|
||||
opaque,
|
||||
read,
|
||||
write,
|
||||
}),
|
||||
error: None,
|
||||
upload: None,
|
||||
}))
|
||||
}
|
||||
|
||||
/// Drops an instance of a backup protocol client. The pointer must be valid or `NULL`.
|
||||
#[no_mangle]
|
||||
pub extern "C" fn proxmox_backup_done(me: *mut CClient) {
|
||||
if !me.is_null() {
|
||||
unsafe {
|
||||
Box::from_raw(me);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Returns a C String describing the last error or `NULL` if there was none.
|
||||
#[no_mangle]
|
||||
pub extern "C" fn proxmox_backup_get_error(me: *const CClient) -> *const c_char {
|
||||
let me = unsafe { &*me };
|
||||
match me.error {
|
||||
Some(ref e) => e.as_ptr(),
|
||||
None => std::ptr::null(),
|
||||
}
|
||||
}
|
||||
|
||||
/// Returns true if the `read` callback had previously returned `EOF`.
|
||||
#[no_mangle]
|
||||
pub extern "C" fn proxmox_backup_is_eof(me: *const CClient) -> bool {
|
||||
let me = unsafe { &*me };
|
||||
me.client.eof()
|
||||
}
|
||||
|
||||
/// The data polling methods usually pass errors from the callbacks through to the original caller.
|
||||
/// Since the protocol needs to be non-blocking-IO safe and therefore able to resumine at any point
|
||||
/// where `-EAGAIN` can be returned by the callbacks, it is up to the caller which errors are to be
|
||||
/// considered fatal, but any error returned by callbacks which is not `-EAGAIN` will result in an
|
||||
/// internal error flag to be set which has to be cleared before trying to resume normal
|
||||
/// operations.
|
||||
#[no_mangle]
|
||||
pub extern "C" fn proxmox_backup_clear_err(me: *mut CClient) {
|
||||
let me = unsafe { &mut *me };
|
||||
me.client.clear_err();
|
||||
me.error = None;
|
||||
}
|
||||
|
||||
/// Polls for data and checks whether the protocol handshake has been made successfully.
|
||||
/// Returns `1` if the handshake was successful, `0` if it is not yet complete or `-1` on error.
|
||||
#[no_mangle]
|
||||
pub extern "C" fn proxmox_backup_wait_for_handshake(me: *mut CClient) -> c_int {
|
||||
let me = unsafe { &mut *me };
|
||||
me.bool_call(move |c| c.wait_for_handshake())
|
||||
}
|
||||
|
||||
fn check_string(s: *const c_char) -> Result<&'static str, Error> {
|
||||
if s.is_null() {
|
||||
bail!("NULL string");
|
||||
}
|
||||
Ok(std::str::from_utf8(unsafe {
|
||||
CStr::from_ptr(s).to_bytes()
|
||||
})?)
|
||||
}
|
||||
|
||||
/// Request the list of hashes for a backup file in order to prevent duplicates from being sent to
|
||||
/// the server. This simply causes an internal list to be filled. Only one such operation can be
|
||||
/// performed simultaneously. To wait for its completion see `proxmox_backup_wait_for_hashes`.
|
||||
///
|
||||
/// If the file name is `NULL` or not a valid UTF-8 string, this function returns an error without
|
||||
/// putting the protocol handler in an error state.
|
||||
///
|
||||
/// Returns `0` on success, `-1` otherwise.
|
||||
#[no_mangle]
|
||||
pub extern "C" fn proxmox_backup_query_hashes(me: *mut CClient, file_name: *const c_char) -> c_int {
|
||||
let me = unsafe { &mut *me };
|
||||
|
||||
me.int_call(move |client| {
|
||||
let file_name = check_string(file_name)?;
|
||||
client.query_hashes(file_name)?;
|
||||
Ok(0)
|
||||
})
|
||||
}
|
||||
|
||||
/// If there is an ongoing hash list request, this will poll the data stream.
|
||||
///
|
||||
/// Returns `1` if the transfer is complete (or there was no transfer to begin with), `0` if it is
|
||||
/// incomplete, or `-1` if an error occurred.
|
||||
#[no_mangle]
|
||||
pub extern "C" fn proxmox_backup_wait_for_hashes(me: *mut CClient) -> c_int {
|
||||
let me = unsafe { &mut *me };
|
||||
me.bool_call(move |c| c.wait_for_hashes())
|
||||
}
|
||||
|
||||
/// Check if a chunk of the provided digest is known to the this client instance. Note that this
|
||||
/// does not query the server for this information, and is only useful after a call to
|
||||
/// `proxmox_backup_query_hashes` or after uploading something.
|
||||
#[no_mangle]
|
||||
pub extern "C" fn proxmox_backup_is_chunk_available(me: *const CClient, digest: *const u8) -> bool {
|
||||
let me = unsafe { &*me };
|
||||
let digest = unsafe { &*(digest as *const [u8; 32]) };
|
||||
me.client.is_chunk_available(digest)
|
||||
}
|
||||
|
||||
/// Begin uploading a chunk to the server. This attempts to upload the data right away, but if the
|
||||
/// writer may fail due to non-blocking I/O in which case the `proxmox_backup_continue_upload`
|
||||
/// function must be used.
|
||||
///
|
||||
/// Returns `0` if the upload is incomplete, a positive ID if the upload was completed immediately,
|
||||
/// or `-1` on error.
|
||||
///
|
||||
/// The ID returned on success can be used to wait for the server to acknowledge that the chunk has
|
||||
/// been written successfully. Use `proxmox_backup_wait_for_id` to do this. If confirmation is not
|
||||
/// required, the ID should be released via `proxmox_backup_discard_id`.
|
||||
#[no_mangle]
|
||||
pub extern "C" fn proxmox_backup_upload_chunk(
|
||||
me: *mut CClient,
|
||||
digest: *const u8,
|
||||
data: *const u8,
|
||||
size: u64,
|
||||
) -> c_int {
|
||||
let me = unsafe { &mut *me };
|
||||
let digest: &[u8; 32] = unsafe { &*(digest as *const [u8; 32]) };
|
||||
let size = size as usize;
|
||||
let slice: &[u8] = unsafe { std::slice::from_raw_parts(data, size) };
|
||||
match me.client.upload_chunk(digest, slice) {
|
||||
Ok(Some(id)) => id.0 as c_int,
|
||||
Ok(None) => {
|
||||
me.upload = Some((data, size));
|
||||
0
|
||||
}
|
||||
Err(e) => me.set_error(e),
|
||||
}
|
||||
}
|
||||
|
||||
/// If an upload did not finish immediately (`proxmox_backup_upload_chunk` returned `0`), this
|
||||
/// function must be used to retry sending the rest of the data.
|
||||
///
|
||||
/// Returns `0` if the upload is incomplete, a positive ID if the upload was completed immediately,
|
||||
/// or `-1` on error.
|
||||
#[no_mangle]
|
||||
pub extern "C" fn proxmox_backup_continue_upload(me: *mut CClient) -> c_int {
|
||||
let me = unsafe { &mut *me };
|
||||
match me.upload {
|
||||
Some((data, len)) => {
|
||||
let slice: &[u8] = unsafe { std::slice::from_raw_parts(data, len) };
|
||||
match me.client.continue_upload_chunk(slice) {
|
||||
Ok(Some(id)) => id.0 as c_int,
|
||||
Ok(None) => 0,
|
||||
Err(e) => me.set_error(e),
|
||||
}
|
||||
}
|
||||
None => me.set_error(format_err!("no upload currently running")),
|
||||
}
|
||||
}
|
||||
|
||||
/// Run the main receive loop. Returns `0` on success, `-1` on error.
|
||||
#[no_mangle]
|
||||
pub extern "C" fn proxmox_backup_poll_read(me: *mut CClient) -> c_int {
|
||||
let me = unsafe { &mut *me };
|
||||
match me.client.poll_read() {
|
||||
Ok(_) => 0,
|
||||
Err(e) => me.set_error(e),
|
||||
}
|
||||
}
|
||||
|
||||
/// Run the main send loop. If the `write` callback returned `-EAGAIN`, during an operation, the
|
||||
/// protocol handler keeps the data to be sent in a write queue. This function will attempt to
|
||||
/// continue writing out the remaining data. See individual function descriptions for when this is
|
||||
/// necessary.
|
||||
///
|
||||
/// Returns `1` if the queue is now empty, `0` if there is still data in the queue, or `-1` on
|
||||
/// error.
|
||||
#[no_mangle]
|
||||
pub extern "C" fn proxmox_backup_poll_send(me: *mut CClient) -> c_int {
|
||||
let me = unsafe { &mut *me };
|
||||
me.bool_call(move |c| Ok(c.poll_send()?.unwrap_or(true)))
|
||||
}
|
||||
|
||||
/// Run the main receive loop and check for confirmation of a stream with the specified ID.
|
||||
///
|
||||
/// Returns `1` if the transaction was confirmed, `0` if not, or `-1` on error.
|
||||
///
|
||||
/// Note that once this function returned `1` for an ID, the id is considered to be free for
|
||||
/// recycling and should not be used for further calls.
|
||||
#[no_mangle]
|
||||
pub extern "C" fn proxmox_backup_wait_for_id(me: *mut CClient, id: c_int) -> c_int {
|
||||
let me = unsafe { &mut *me };
|
||||
me.bool_call(move |c| c.wait_for_id(crate::StreamId(id as u8)))
|
||||
}
|
||||
|
||||
/// Notifies the protocol handler that we do not bother waiting for confirmation of an ID. The ID
|
||||
/// may immediately be recycled for future transactions, thus the user should not use it for any
|
||||
/// further function calls.
|
||||
///
|
||||
/// Returns `0` on success, `-1` on error.
|
||||
#[no_mangle]
|
||||
pub extern "C" fn proxmox_backup_discard_id(me: *mut CClient, id: c_int) -> c_int {
|
||||
let me = unsafe { &mut *me };
|
||||
match me.client.discard_id(crate::StreamId(id as u8)) {
|
||||
Ok(_) => 0,
|
||||
Err(e) => me.set_error(e),
|
||||
}
|
||||
}
|
||||
|
||||
/// Create a new backup. The returned ID should be waited upon via `proxmox_backup_wait_for_id`,
|
||||
/// which returns true once the server confirmed the creation of the backup.
|
||||
#[no_mangle]
|
||||
pub extern "C" fn proxmox_backup_create(
|
||||
me: *mut CClient,
|
||||
dynamic: bool,
|
||||
backup_type: *const c_char, // "host", "ct", "vm"
|
||||
backup_id: *const c_char,
|
||||
time_epoch: i64,
|
||||
file_name: *const c_char,
|
||||
chunk_size: c_ulong,
|
||||
file_size: i64,
|
||||
is_new: bool,
|
||||
) -> c_int {
|
||||
let me = unsafe { &mut *me };
|
||||
me.int_call(move |client| {
|
||||
let index_type = match dynamic {
|
||||
false => crate::IndexType::Fixed,
|
||||
_ => crate::IndexType::Dynamic,
|
||||
};
|
||||
|
||||
let backup_type = check_string(backup_type)?;
|
||||
let backup_id = check_string(backup_id)?;
|
||||
let file_name = check_string(file_name)?;
|
||||
|
||||
Ok(client
|
||||
.create_backup(
|
||||
index_type,
|
||||
backup_type,
|
||||
backup_id,
|
||||
time_epoch,
|
||||
file_name,
|
||||
chunk_size as _,
|
||||
if file_size < 0 {
|
||||
None
|
||||
} else {
|
||||
Some(file_size as u64)
|
||||
},
|
||||
is_new,
|
||||
)?
|
||||
.0 as c_int)
|
||||
})
|
||||
}
|
||||
|
||||
/// Send a dynamic chunk entry.
|
||||
///
|
||||
/// If the entry was sent out successfully this returns `1`. If the `write` callback returned
|
||||
/// `-EAGAIN` this returns `0` and the data is queued, after which `proxmox_backup_poll_send`
|
||||
/// should be used to continue sending the data.
|
||||
/// On error `-1` is returned.
|
||||
#[no_mangle]
|
||||
pub extern "C" fn proxmox_backup_dynamic_data(
|
||||
me: *mut CClient,
|
||||
stream: c_int,
|
||||
digest: *const [u8; 32],
|
||||
size: u64,
|
||||
) -> c_int {
|
||||
let me = unsafe { &mut *me };
|
||||
me.bool_call(move |client| {
|
||||
client.dynamic_data(crate::BackupStream(stream as u8), unsafe { &*digest }, size)
|
||||
})
|
||||
}
|
||||
|
||||
/// Send a fixed chunk entry.
|
||||
///
|
||||
/// If the entry was sent out successfully this returns `1`. If the `write` callback returned
|
||||
/// `-EAGAIN` this returns `0` and the data is queued, after which `proxmox_backup_poll_send`
|
||||
/// should be used to continue sending the data.
|
||||
/// On error `-1` is returned.
|
||||
#[no_mangle]
|
||||
pub extern "C" fn proxmox_backup_fixed_data(
|
||||
me: *mut CClient,
|
||||
stream: c_int,
|
||||
index: c_ulong,
|
||||
digest: *const [u8; 32],
|
||||
) -> c_int {
|
||||
let me = unsafe { &mut *me };
|
||||
me.bool_call(move |client| {
|
||||
client.fixed_data(crate::BackupStream(stream as u8), index as usize, unsafe {
|
||||
&*digest
|
||||
})
|
||||
})
|
||||
}
|
||||
Reference in New Issue
Block a user