Cargo.toml
README.md
www/index.md
www/changelog.md
src/err.rs
src/lib.rs
src/path.rs
src/fs.rs
src/strx.rs

src/buf.rs
src/sqlfuncs.rs
src/futures.rs
src/iox.rs
src/tokiox.rs
src/tokiox/tcpconn.rs
src/serde_parsers.rs
src/setops.rs

tests/setops.rs
examples/fut_if_some.rs
examples/deser.rs
examples/slasher.rs

[package]
name = "orphanage"
version = "0.1.4"
edition = "2021"
license = "0BSD"
# https://crates.io/category_slugs
categories = [ "network-programming" ]
keywords = [ "sqlite", "fs", "path" ]
repository = "https://repos.qrnch.tech/pub/orphanage"
description = "Random collection of stuff that is still searching for a home."

]

# https://doc.rust-lang.org/cargo/reference/manifest.html#the-badges-section
[badges]
maintenance = { status = "experimental" }

[features]
tokio = ["dep:tokio", "dep:async-trait", "dep:killswitch"]
rusqlite = ["dep:rusqlite", "dep:sha2"]
serde = ["dep:serde", "dep:parse-size"]

[dependencies]
async-trait = { version = "0.1.82", optional = true }
hashbrown = { version = "0.15.1" }
killswitch = { version = "0.4.2", optional = true }
parse-size = { version = "1.1.0", optional = true }

rand = { version = "0.8.5" }
rusqlite = { version = "0.32.1", optional = true, features = ["functions"] }
serde = { version = "1.0.214", optional = true, features = ["derive"] }
sha2 = { version = "0.10.7", optional = true }

shellexpand = { version = "3.1.0" }
tokio = { version = "1.41.0", optional = true, features = [
  "macros", "net", "time"
] }











[dev-dependencies]

killswitch = { version = "0.4.2" }
tokio = { version = "1.40.0", features = ["full"] }
tokio-test = { version = "0.4.3" }
toml = { version = "0.8.18" }

[package.metadata.docs.rs]
all-features = true
rustdoc-args = ["--cfg", "docsrs", "--generate-link-to-definition"]

[lints.clippy]
all = { level = "warn", priority = -1 }
pedantic = { level = "warn", priority = -1 }
nursery = { level = "warn", priority = -1 }
cargo = { level = "warn", priority = -1 }

multiple_crate_versions = "allow"

  let mut buf = Vec::with_capacity(len);

  // SAFETY: Presumably with_capacity() works as documented.
  unsafe {
    buf.set_len(len);
  }

  rand::thread_rng().fill(&mut buf[..]);

  buf
}

// vim: set ft=rust et sw=2 ts=2 sts=2 cinoptions=2 tw=79 :

use std::{
  fs,
  io::ErrorKind,
  path::{Path, PathBuf}
};



use crate::err::Error;


/// Create a random file of a specified size.
///
/// # Errors
/// [`std::io::Error`]
pub fn rndfile(
  fname: impl AsRef<Path>,

pub fn abspath<P>(pth: P) -> Result<PathBuf, Error>
where
  P: AsRef<Path>
{
  Ok(pth.as_ref().canonicalize()?)
}


/// Call a closure if `outfile` is outdated (according to the rules of
/// [`outdated()`] with regards to `infile`.
///
/// Returns `Ok(true)` if the closure was called.
///
/// # Errors
/// Errors mirror the behavior of [`outdated()`]'s errors.

  let in_mtime = in_md.modified()?;
  let out_mtime = out_md.modified()?;

  Ok(in_mtime > out_mtime)
}












































































// vim: set ft=rust et sw=2 ts=2 sts=2 cinoptions=2 tw=79 :

    if let Some(ref mut remain) = self.0 {
      if *remain == 0 {
        // signal eof
        Ok(0)
      } else {
        let n = std::cmp::min(*remain, buf.len() as u64);
        let len = usize::try_from(n).unwrap();
        rand::thread_rng().fill(&mut buf[..len]);
        *remain -= n;
        Ok(len)
      }
    } else {
      rand::thread_rng().fill(&mut buf[..]);
      Ok(buf.len())
    }
  }
}

// vim: set ft=rust et sw=2 ts=2 sts=2 cinoptions=2 tw=79 :

#![cfg_attr(docsrs, feature(doc_cfg))]

pub mod buf;
mod err;

pub mod fs;
pub mod futures;
pub mod iox;

pub mod path;
pub mod setops;
pub mod strx;

#[cfg(feature = "rusqlite")]
#[cfg_attr(docsrs, doc(cfg(feature = "rusqlite")))]
pub mod sqlfuncs;

#[cfg(feature = "tokio")]
#[cfg_attr(docsrs, doc(cfg(feature = "tokio")))]
pub mod tokiox;

#[cfg(feature = "tokio")]
#[cfg_attr(docsrs, doc(cfg(feature = "tokio")))]
pub use async_trait::async_trait;

#[cfg(feature = "serde")]
#[cfg_attr(docsrs, doc(cfg(feature = "serde")))]
pub mod serde_parsers;

pub use err::Error;

// vim: set ft=rust et sw=2 ts=2 sts=2 cinoptions=2 tw=79 :

use rusqlite::{functions::FunctionFlags, Connection, Error};

use sha2::{Digest, Sha256};

use crate::strx::{validate_objname, RndStr};

/// Add a `hashstr()` SQL function to the connection object.
///
/// The SQL function `hashstr()` takes two arguments:
/// 1. The algorithm that will be used to hash the input.
/// 2. The input string to hash.
///
/// Currently only the algorithm `sha2/256` is supported.
///
/// ```
/// use rusqlite::Connection;
/// use orphanage::sqlfuncs;
///
/// let conn = Connection::open_in_memory().unwrap();
/// sqlfuncs::hashstr(&conn).unwrap();
/// let instr = "hello, world";
/// let hstr: String = conn.query_row_and_then(
///   "SELECT lower(hex(hashstr('sha2/256', ?)));",
///   [instr],
///   |row| {
///     row.get(0)
///   }
///   ).unwrap();
/// assert_eq!(&hstr[..8], "09ca7e4e");
/// ```
#[allow(clippy::missing_errors_doc)]
pub fn hashstr(conn: &Connection) -> Result<(), Error> {
  conn.create_scalar_function(
    "hashstr",
    2,
    FunctionFlags::SQLITE_UTF8 | FunctionFlags::SQLITE_DETERMINISTIC,
    move |ctx| {
      //assert_eq!(ctx.len(), 2, "called with unexpected number of
      // arguments");
      let algo = ctx.get::<String>(0)?.to_lowercase();
      let s = ctx.get::<String>(1)?;

      let mut hasher = match algo.as_ref() {
        "sha2/256" => Sha256::new(),
        _ => Err(Error::UserFunctionError("Bad hash algo".into()))?
      };
      hasher.update(s.as_bytes());
      let result = hasher.finalize();

      Ok(result[..].to_vec())
    }
  )
}

/// Add a `hashblob()` SQL function to the connection object.
///
/// The SQL function `hashblob()` takes two arguments:
/// 1. The algorithm that will be used to hash the input.
/// 2. The input string to hash.
///
/// Currently only the algorithm `sha2/256` is supported.
///
/// ```
/// use rusqlite::Connection;
/// use orphanage::sqlfuncs;
///
/// let conn = Connection::open_in_memory().unwrap();
/// sqlfuncs::hashblob(&conn).unwrap();
/// let buf = b"hello, world";
/// let hstr: String = conn.query_row_and_then(
///   "SELECT lower(hex(hashblob('sha2/256', ?)));",
///   [&buf],
///   |row| {
///     row.get(0)
///   }
///   ).unwrap();
/// assert_eq!(&hstr[..8], "09ca7e4e");
/// ```
#[allow(clippy::missing_errors_doc)]
pub fn hashblob(conn: &Connection) -> Result<(), Error> {
  conn.create_scalar_function(
    "hashblob",
    2,
    FunctionFlags::SQLITE_UTF8 | FunctionFlags::SQLITE_DETERMINISTIC,
    move |ctx| {
      //assert_eq!(ctx.len(), 2, "called with unexpected number of
      // arguments");
      let algo = ctx.get::<String>(0)?.to_lowercase();
      let blob = ctx.get::<Vec<u8>>(1)?;

      let mut hasher = match algo.as_ref() {
        "sha2/256" => Sha256::new(),
        _ => Err(Error::UserFunctionError("Bad hash algo".into()))?
      };
      hasher.update(&blob);
      let result = hasher.finalize();

      Ok(result[..].to_vec())
    }
  )
}

/// Add a `randomstr()` SQL function to the connection object.
///
/// The SQL function `randomstr()` takes a single argument:
/// 1. The length of the random string, in characters.
///
/// Its output will be a random string of the requested length where each
/// character is a ASCII alphabet or numeric character.
///
/// ```
/// use rusqlite::Connection;
/// use orphanage::sqlfuncs;
///
/// let conn = Connection::open_in_memory().unwrap();
/// sqlfuncs::rndstr_alphanum(&conn).unwrap();
///
/// conn.execute(r#"
/// CREATE TABLE IF NOT EXISTS stuff (
///   id   INTEGER PRIMARY KEY,
///   salt TEXT NOT NULL DEFAULT (randomstr(8))
/// );
/// "#, []);
/// ```
#[allow(clippy::missing_errors_doc)]
pub fn rndstr_alphanum(db: &Connection) -> Result<(), Error> {
  db.create_scalar_function(
    "randomstr",
    1,
    FunctionFlags::SQLITE_UTF8,
    move |ctx| {
      //assert_eq!(ctx.len(), 1, "called with unexpected number of
      // arguments");
      let len = ctx.get::<usize>(0)?;

      Ok(String::rnd_alphanum(len))
    }
  )
}

#[allow(clippy::missing_errors_doc)]
pub fn rndstr(db: &Connection) -> Result<(), Error> {
  db.create_scalar_function(
    "randomstr",
    2,
    FunctionFlags::SQLITE_UTF8,
    move |ctx| {
      //assert_eq!(ctx.len(), 2, "called with unexpected number of
      // arguments");
      let len = ctx.get::<usize>(0)?;
      let alphabet = ctx.get::<String>(1)?;
      let charset = alphabet.as_bytes();

      Ok(String::rnd_from_alphabet(len, charset))
    }
  )
}

/// Add a `isobjname()` SQL function to the connection object.
///
/// The SQL function `isobjname()` takes a signle argument:
/// 1. The input string to check whether it conforms to an object name.
///
/// ```
/// use rusqlite::Connection;
/// use orphanage::sqlfuncs;
///
/// let conn = Connection::open_in_memory().unwrap();
/// sqlfuncs::hashstr(&conn).unwrap();
///
/// conn.execute(r#"
/// CREATE TABLE IF NOT EXISTS stuff (
///   id   INTEGER PRIMARY KEY,
///   name TEXT UNIQUE NOT NULL,
///   CHECK (isobjname(name) == 1)
/// );
/// "#, []);
/// ```
///
/// # Panics
/// The number of input parameters must be exactly 1.
#[allow(clippy::missing_errors_doc)]
pub fn isobjname(conn: &Connection) -> Result<(), Error> {
  conn.create_scalar_function(
    "isobjname",
    1,
    FunctionFlags::SQLITE_UTF8 | FunctionFlags::SQLITE_DETERMINISTIC,
    move |ctx| {
      assert_eq!(ctx.len(), 1, "called with unexpected number of arguments");
      let name = ctx.get::<String>(0)?;
      validate_objname(&name)
        .map_err(|e| Error::UserFunctionError(Box::new(e)))?;
      Ok(1)
    }
  )
}

// vim: set ft=rust et sw=2 ts=2 sts=2 cinoptions=2 tw=79 :

//! Extended str/string functionality.

use rand::{distributions::Alphanumeric, Rng};

use crate::err::Error;

pub trait RndStr {
  fn rnd_alphanum(len: usize) -> String;
  fn rnd_from_alphabet(len: usize, alpha: &[u8]) -> String;
}

impl RndStr for String {
  /// Generate a random alphanumeric string of a requested length.
  fn rnd_alphanum(len: usize) -> String {
    rand::thread_rng()
      .sample_iter(&Alphanumeric)
      .take(len)
      .map(char::from)
      .collect()
  }

  /// Generate a random string of a requested length, given an alphabet of
  /// acceptable characters.
  ///
  /// ```
  /// use orphanage::strx::RndStr;
  ///
  /// const CHARSET: &[u8] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZ\
  ///                          abcdefghijklmnopqrstuvwxyz\
  ///                          0123456789-_";
  ///
  /// let s = String::rnd_from_alphabet(16, CHARSET);
  /// assert_eq!(s.len(), 16);
  /// ```
  fn rnd_from_alphabet(len: usize, charset: &[u8]) -> String {
    let mut rng = rand::thread_rng();
    (0..len)
      .map(|_| {
        let idx = rng.gen_range(0..charset.len());
        charset[idx] as char
      })
      .collect()
  }
}

pub const OBJNAME_SPEC: &str = "must be non-empty, lead with an alphabetic \
                                character, with each following character \
                                being alphanumeric, '_', '-' or '.'";


#[allow(clippy::missing_errors_doc)]
pub fn validate_name<L, R>(s: &str, lead: L, rest: R) -> Result<(), Error>
where
  L: Fn(char) -> bool,
  R: Fn(char) -> bool
{
  let mut chars = s.chars();
  let Some(ch) = chars.next() else {
    return Err(Error::BadFormat(
      "Object name must not be empty".to_string()
    ));
  };
  if !lead(ch) {
    return Err(Error::BadFormat(
      "Invalid leading object name character".to_string()
    ));
  }
  if chars.any(|c| !rest(c)) {
    return Err(Error::BadFormat(
      "Invalid object name character".to_string()
    ));
  }
  Ok(())
}

#[inline]
#[allow(clippy::missing_errors_doc)]
pub fn validate_objname(s: &str) -> Result<(), Error> {
  validate_name(s, is_name_leading_char, is_name_char)
}


#[cfg(test)]
mod tests {
  use super::*;

//! tokio extensions.
//!
//! # Connector
//! The _Connector_ subsystem consists of two parts:
//! - The [`Connector`] trait is implemented by applications/libraries that
//!   want to run retryable connection loops.
//! - [`run_connector()`] is a function that takes in a `Connector`
//!   implementation, and attempts to establish a connection and calls the
//!   [`Connector::run()`] once a connection has been successfully been
//!   established.
//!
//! Paradoxically the `run_connector()` function does not itself actually
//! attemtp to establish any connections -- it relies on the `Connector` trait
//! to implement the means to establish connections.
//!
//! The "good path" overall flow of the connector loop is to call the
//! `connect()` method. If it is successful, call the `run()` method, passing
//! along the newly allocated connection. The main application logic relating
//! to the connection should called from this method.
//!
//! The primary purpose of the connector concerns the "failure path":  If the
//! `connect()` method encounters a failure it can choose to signal to back to
//! the connector loop that the error is "retryable", in which case the
//! `retry_delay()` method is called to determine if the connector loop should
//! retry (and implement a delay before returning instructions to do so).
//!
//! Likewise, the `run()` method returns its `Result<(), Self::Error>` wrapped
//! in a `ControlFlow::Continue(_)` to indicate that the connector look should
//! reconnect, while `ControlFlow::Break(_)` signals that a fatal error occured
//! and the connect loop should terminate.

pub mod tcpconn;

use std::ops::ControlFlow;

use async_trait::async_trait;

pub use tcpconn::SimpleTcpConnector;


/// Application callbacks for the [`run_connector()`] function (or equivalent).
#[async_trait]
pub trait Connector {
  /// The connection return type.
  type ConnType: Send;

  /// The application return type.
  type Error;

  /// Establish a connection.
  ///
  /// If a connection was successfully established the implementation should
  /// return `Ok(Self::ConnType)`.
  ///
  /// If an error is returned as `Err(ControlFlow::Continue(Self::Error))` it
  /// signals to the connector loop that the error is non-fatal, and that the
  /// connection should be retried.  Returning an error as
  /// `Err(ControlFlow::Break(Self::Error))` signals that there's no point in
  /// trying to (re)connect (with the same configuration) and the
  /// (re)connection loop is terminated.
  async fn connect(
    &mut self
  ) -> Result<Self::ConnType, ControlFlow<Self::Error, Self::Error>>;

  /// Give application a chance to determine whether or not to attempt a
  /// reconnection, and delay before doing so.
  ///
  /// Implementations return `ControlFlow::Continue(())` to signal to the
  /// connector loop that it should retry the connection.  Returnning
  /// `ControlFlow::Break(Self::Error)` will terminate the connector loop and
  /// cause it to return the error.
  async fn retry_delay(&mut self) -> ControlFlow<Self::Error>;

  /// Run the application's connection handler.
  ///
  /// The application should return `ControlFlow::Continue(_)` to request that
  /// the connector loop delay and reconnect.  Returning
  /// `ControlFlow::Break(_)` will cause the connect loop to terminate and
  /// return the suppied result.
  async fn run(
    &mut self,
    conn: Self::ConnType
  ) -> ControlFlow<Result<(), Self::Error>, Result<(), Self::Error>>;
}


/// Establish a network connection.
///
/// The `run_connector()` function will enter a loop that will attempt to
/// establish a connection and call the `Connector::run()` implementation once
/// succesful.  If the connection fails, `Connector::retry_delay()` will be
/// called to determine whether to retry the connection.
///
/// # Exit conditions
/// The (re)connection loop will keep running until an exit condition has been
/// triggered:
/// - [`Connector::connect()`] returns `Err(ControlFlow::Break(Self::Error))`
/// - [`Connector::retry_delay()`] returns `ControlFlow::Break(Self::Error)`.
/// - [`Connector::run()`] returns `ControlFlow::Break(Result<(),
///   Self::Error>)`
#[deprecated(since = "0.0.3", note = "use `schmoozer` crate instead")]
#[allow(clippy::missing_errors_doc)]
pub async fn run_connector<E>(
  mut connector: impl Connector<Error = E> + Send
) -> Result<(), E>
where
  E: Send
{
  loop {
    // Call the application's connect callback to attempt to establish
    // connection.
    match connector.connect().await {
      Ok(conn) => {
        // A connection was successfully established -- call the run()
        // implementation.
        match connector.run(conn).await {
          ControlFlow::Continue(_res) => {
            // The application has requested a reconnection.
            // Fall through to retry()/delay()
          }
          ControlFlow::Break(res) => {
            // Break out of loop -- passing along the result from the
            // application.
            break res;
          }
        }
      }
      Err(ControlFlow::Continue(_res)) => {
        // The connector returned a retriable error
        // fall through to retry()/delay()
      }
      Err(ControlFlow::Break(res)) => {
        // The connector returned a fatal error
        break Err(res);
      }
    }

    // If this point is reached the application has requested a reconnection.
    // Call `retry_delay()` to allow the application to determine whether to
    // retry or not.

    match connector.retry_delay().await {
      ControlFlow::Continue(()) => {
        // Application wants to reconnect.
        continue;
      }
      ControlFlow::Break(err) => {
        // Application does not want to reconnect
        break Err(err);
      }
    }
  }
}


/// If a timeout has been specified, sleep until then.
///
/// Otherwise wait forever.
///
/// Can be used to timeout select loops.
pub async fn sleep_until_if_some(at: Option<tokio::time::Instant>) {

use std::{future::Future, io::ErrorKind, ops::ControlFlow, time::Duration};

use tokio::net::TcpStream;

use async_trait::async_trait;

use killswitch::KillSwitch;

use super::Connector;

pub struct SimpleTcpConnector<F>
where
  F: Future<
    Output = ControlFlow<
      Result<(), std::io::Error>,
      Result<(), std::io::Error>
    >
  >
{
  addr: String,
  delay: usize,
  ks: KillSwitch,
  cb: Box<dyn Fn(TcpStream, KillSwitch) -> F + Send>
}

impl<F> SimpleTcpConnector<F>
where
  F: Future<
    Output = ControlFlow<
      Result<(), std::io::Error>,
      Result<(), std::io::Error>
    >
  >
{
  #[must_use]
  pub fn new(
    addr: String,
    ks: KillSwitch,
    cb: Box<dyn Fn(TcpStream, KillSwitch) -> F + Send>
  ) -> Self {
    Self {
      addr,
      delay: 1,
      ks,
      cb
    }
  }
}

#[async_trait]
impl<F> Connector for SimpleTcpConnector<F>
where
  F: Future<
      Output = ControlFlow<
        Result<(), std::io::Error>,
        Result<(), std::io::Error>
      >
    > + Send
{
  type Error = std::io::Error;
  type ConnType = TcpStream;

  async fn connect(
    &mut self
  ) -> Result<Self::ConnType, ControlFlow<Self::Error, Self::Error>> {
    tokio::select! {
      res = TcpStream::connect(&self.addr) =>  {
        match res {
          Ok(conn) => Ok(conn),
          Err(e) => match e.kind() {
            ErrorKind::ConnectionAborted | ErrorKind::NotConnected => {
              Err(ControlFlow::Continue(e))
            }
            _ => Err(ControlFlow::Break(e))
          }
        }
      }
      () = self.ks.wait() => {
        // Aborted -- use ErrorKind::Other to signal abortion
        let err = std::io::Error::other(String::from("aborted"));
        Err(ControlFlow::Break(err))
      }
    }
  }

  async fn retry_delay(&mut self) -> ControlFlow<Self::Error> {
    let dur = Duration::from_secs(self.delay.try_into().unwrap());
    tokio::select! {
      () = self.ks.wait() => {
        let err = std::io::Error::other(String::from("aborted"));
        ControlFlow::Break(err)
      }
      () = tokio::time::sleep(dur) => {
        // double sleep duration for each iteration, but cap at 60 seconds
        self.delay = std::cmp::min(self.delay * 2, 60);
        ControlFlow::Continue(())
      }
    }
  }

  async fn run(
    &mut self,
    conn: Self::ConnType
  ) -> ControlFlow<Result<(), Self::Error>, Result<(), Self::Error>> {
    // reset delay
    self.delay = 1;

    let fut = (self.cb)(conn, self.ks.clone());

    fut.await
  }
}

// vim: set ft=rust et sw=2 ts=2 sts=2 cinoptions=2 tw=79 :

# Change Log



## [Unreleased]













[Details](/vdiff?from=orphanage-0.1.4&to=trunk)

### Added



### Changed





### Removed








---

## [0.1.4] - 2024-11-22

[Details](/vdiff?from=orphanage-0.1.3&to=orphanage-0.1.4)

### Added

The crate's documentation uses automatically generated feature labels, which
currently requires nightly featuers.  To build the documentation locally use:

```
RUSTFLAGS="--cfg docsrs" RUSTDOCFLAGS="--cfg docsrs" cargo +nightly doc --all-features
```