Cargo.toml
README.md
www/index.md
www/changelog.md
src/err.rs
src/lib.rs
src/types.rs
src/types/telegram.rs
src/types/params.rs
src/types/kvlines.rs
src/types/validators.rs
src/codec.rs
src/codec/utils.rs
tests/*.rs

[package]
name = "blather"
version = "0.10.1"
edition = "2021"
license = "0BSD"
keywords = [ "line-based", "protocol", "tokio", "codec" ]
repository = "https://repos.qrnch.tech/pub/blather"
description = "A talkative line-based protocol"
exclude = [
  ".fossil-settings",
  ".efiles",
  ".fslckout",
  "rustfmt.toml",
  "www"
]

[dependencies]
bytes = { version = "1.7.1" }
futures = { version = "0.3.30" }

tokio = { version = "1.39.2" }
tokio-stream = { version = "0.1.15" }
tokio-util = { version= "0.7.11", features = ["codec"] }

[dev-dependencies]
tokio = { version = "1.39.2", features = ["macros", "net"] }

tokio-test = { version = "0.4.4" }

[package.metadata.docs.rs]
rustdoc-args = ["--generate-link-to-definition"]

# vim: set ft=toml et sw=2 ts=2 sts=2 cinoptions=2 tw=79 :

# blather

A talkative, somwhat reminiscent of HTTP, line-based protocol, implemented as
a tokio-util Codec.

//! A [`tokio_util::codec`] Codec that is used to encode and decode the
//! blather protocol.

pub mod utils;

use std::{
  fmt,
  {cmp, collections::HashMap, mem}
};

use bytes::{BufMut, Bytes, BytesMut};

//! Helpers used to perform common framed stream operation.

use tokio::io::AsyncRead;

use tokio_util::codec::Framed;

use tokio_stream::StreamExt;

use crate::{
  codec::{self, Codec},
  err::Error,
  Telegram
};


/// Validation callback result.
pub enum Outcome {
  /// The Telegram should be returned to the application.
  Accept,

  /// The Telefgram should be ignored.
  Ignore,

  /// Tell the caller that a fatal error occurred.
  Fail(Error)
}

/// Receive a [`Telegram`] from a `Frame`'d stream.
///
/// The callback in `validate` can be used to inspect the received `Telegram`
/// and choose whether to return/ignore it or return a fatal error.
///
/// If the connection is closed this function will return `Ok(None)`.
pub async fn expect_telegram<T, F>(
  frmio: &mut Framed<T, Codec>,
  validate: F
) -> Result<Option<Telegram>, Error>
where
  T: AsyncRead + Unpin,
  F: Fn(&Telegram) -> Outcome
{
  loop {
    let Some(frm) = frmio.next().await else {
      // Got None, which (probably) means the connection has ended.
      break Ok(None);
    };
    let frm = match frm {
      Ok(frm) => frm,
      Err(e) => {
        break Err(Error::Protocol(e.to_string()));
      }
    };
    let codec::Input::Telegram(tg) = frm else {
      // If a non-Telegram is received, then abort and close connection
      break Err(Error::Protocol(
        "Did not receive an expected Telegram".into()
      ));
    };
    match validate(&tg) {
      Outcome::Accept => break Ok(Some(tg)),
      Outcome::Ignore => continue,
      Outcome::Fail(e) => break Err(e)
    }
  }
}

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

  fn from(params: Params) -> Self {
    Telegram {
      params,
      ..Default::default()
    }
  }
}

impl TryFrom<(&str, Params)> for Telegram {
  type Error = Error;

  fn try_from(t: (&str, Params)) -> Result<Self, Self::Error> {
    let mut tg = Telegram::new_topic(t.0)?;
    tg.params = t.1;
    Ok(tg)
  }
}

impl From<HashMap<String, String>> for Telegram {
  fn from(hm: HashMap<String, String>) -> Self {
    Telegram {
      params: Params::from(hm),
      ..Default::default()
    }

use blather::{Error, Params, Telegram};


#[test]
fn simple() {
  let mut msg = Telegram::new();

  msg.set_topic("SomeTopic").unwrap();
  assert_eq!(msg.get_topic().unwrap(), "SomeTopic");

  let mut tg = Telegram::new();
  assert_eq!(
    tg.set_topic("Some Topic"),
    Err(Error::BadFormat("Invalid topic character".to_string()))
  );
}


#[test]
fn create_from_tuple() {
  let mut params = Params::new();
  params.add_str("my", "word").unwrap();
  let tg = Telegram::try_from(("Hello", params)).unwrap();

  assert_eq!(tg.get_str("my"), Some("word"));
}

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

# Change Log

⚠️  indicates a breaking change.

## [Unreleased]

[Details](/vdiff?from=blather-0.10.1&to=trunk)

### Added

### Changed

### Removed

---

## [0.10.1] - 2024-08-06

[Details](/vdiff?from=blather-0.10.0&to=blather-0.10.1)

### Added

- Module `codec::utils` added for collecting `Frame`'d stream helpers.
- `codec::utils::expect_telegram()` can be used to receive `Telegram`s with
  simple validation.
- Add `TryFrom<(&str, Params)>` implementation for `Telegram`.

---

## [0.10.0] - 2024-02-23

[Details](/vdiff?from=blather-0.9.0&to=blather-0.10.0)

### Changed

# blather

A talkative, somwhat reminiscent of HTTP, line-based protocol, implemented as
a tokio-util Codec.


## Change log

The details of changes can always be found in the timeline, but for a
high-level view of changes between released versions there's a manually