[package]
name = "lstngrp"
version = "0.0.5"
edition = "2021"
license = "0BSD"
# https://crates.io/category_slugs
categories = [ "network-programming", "asynchronous" ]
keywords = [ "network", "server", "listen", "protwrap" ]
repository = "https://repos.qrnch.tech/pub/lstngrp"
description = "Groups listeners and connections with common data/logic."

]

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

[dependencies]
hashbrown = { version = "0.15.0" }
idbag = { version = "0.2.1" }
killswitch = { version = "0.4.2" }
parking_lot = { version = "0.12.3" }
protwrap = { version = "0.3.0", features = [
  "tls", "tokio"
] }
tokio = { version = "1.40.0", features = [
  "macros", "net", "rt", "sync"

# lstngrp

`ListenGroup` is meant to collect a group of network listeners into a single
entity, and help track connections made against those listeners.

use std::{str::FromStr, sync::Arc};

use parking_lot::Mutex;

use hashbrown::HashMap;

use lstngrp::{
  async_trait, ArcIdUsize, ConnHandler, ConnInfo, GroupHandler, ListenGroup,
  Listener, ListenerSpec, SockAddr, Stream
};

struct ListenCtx {
  name: String
}

    }
  }
}


struct MyConnHandler {
  listen_id: i64,
  conn_id: ArcIdUsize
}

#[async_trait]
impl ConnHandler for MyConnHandler {
  async fn run(&self, _conn: Stream) {
    println!(
      "Run connection {} from listener={}",

use std::str::FromStr;

use lstngrp::{
  async_trait, ArcIdUsize, ConnHandler, ConnInfo, GroupHandler, ListenGroup,
  Listener, ListenerSpec, SockAddr, Stream
};

struct MyHandler {}

#[async_trait]
impl GroupHandler for MyHandler {

    }
  }
}


struct MyConnHandler {
  listen_id: i64,
  conn_id: ArcIdUsize
}

#[async_trait]
impl ConnHandler for MyConnHandler {
  async fn run(&self, _conn: Stream) {
    println!(
      "Run connection {} from listener={}",

use hashbrown::HashMap;

pub use protwrap::tokio::server::{
  listener::{async_trait, Listener, SockAddr},
  Stream
};

pub use idbag::ArcIdUsize;

use idbag::IdBagUsize;

use conn::ConnectionData;

use listener::{ListenData, ListenTaskParams};


/// Internal alias for a `GroupHandler` with a generic listener identifier and
/// connection handler.
type LCHandler<LI, CC> =
  dyn GroupHandler<ListenIdent = LI, ConnHandler = CC> + Send + Sync + 'static;


/// Context passed to [`GroupHandler::connected()`] used to pass connection
/// (metadata) information.
#[derive(Clone)]
pub struct ConnInfo {
  /// The connecting client's address.
  pub sa: Arc<SockAddr>,

  /// The unique client connection id.
  pub id: ArcIdUsize
}


/// Group listener handler.
#[async_trait]
pub trait GroupHandler {
  /// Unique listener identifier type.

  LI: Hash + Eq
{
  /// Keep track of all listeners, identified by `LI` and all their active
  /// connections, identified by an `ArcId`, with their connection context,
  /// identified by `CC`.
  lmap: Arc<Mutex<HashMap<LI, ListenData>>>,

  cmap: Arc<Mutex<HashMap<ArcIdUsize, ConnectionData<LI, CC>>>>,

  /// Connection handler used by all the listeners within this group.
  lhandler: Arc<LCHandler<LI, CC>>,

  idbag: Arc<IdBagUsize>,

  shutdown: Arc<AtomicBool>
}


impl<LI, CC> ListenGroup<LI, CC>
where
  LI: Hash + Eq + Send + Sync + Clone + 'static,
  CC: ConnHandler + Send + Sync + 'static
{
  /// Create a new listener group.
  pub fn new(
    handler: impl GroupHandler<ListenIdent = LI, ConnHandler = CC>
      + Send
      + Sync
      + 'static
  ) -> Self {
    // ToDo: Allow this to be passed in from the application
    let idbag = Arc::new(IdBagUsize::new());

    Self {
      lmap: Arc::new(Mutex::new(HashMap::new())),
      lhandler: Arc::new(handler),
      cmap: Arc::new(Mutex::new(HashMap::new())),
      idbag,
      shutdown: Arc::new(AtomicBool::new(false))

    }
  }

  /// Terminate a connection given a connection identifier.
  ///
  /// This function will not return until the background connection task has
  /// terminated.
  pub async fn kill_connection(&self, cid: ArcIdUsize) {
    // Extraction of join handle placed in a scope so that clippy doesn't think
    // the lock is held over an await point.
    let mut jh = {
      let mut cmap = self.cmap.lock();
      let Some(cdata) = cmap.get_mut(&cid) else {
        // No such id found
        return;

  pub conns: Vec<CInfo<CC>>
}

/// Information returned about a connection when a listen group's current state
/// is inspected.
pub struct CInfo<CC> {
  /// The client connection's internal identifier.
  pub id: ArcIdUsize,

  /// The client connection handler.
  pub chandler: Arc<CC>
}

// 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=lstngrp-0.0.5&to=trunk)

### Added

### Changed

### Removed

---

## [0.0.5] - 2024-10-02

[Details](/vdiff?from=lstngrp-0.0.4&to=lstngrp-0.0.5)

### Changed

- No longer rename `ArcIdUsize` to `ArcId` for the export, because it turned
  out to cause confusion.

---

## [0.0.4] - 2024-09-20

[Details](/vdiff?from=lstngrp-0.0.3&to=lstngrp-0.0.4)

### Added

- Support automatically closing connections when a listener is removed.

### Changed

# lstngrp

`ListenGroup` is meant to collect a group of network listeners into a single
entity, and help track connections made against those listeners.


## 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