Struct brokaw::NntpConnection

pub struct NntpConnection { /* fields omitted */ }

A raw connection to an NNTP Server

NntpConnection essentially wraps a stream. It is responsible for serializing commands and deserializing and parsing responses from the server.

NntpConnection DOES...

• Work very hard not to allocate while reading/parsing response
• Provide facilities for you to manage your own read buffers
• Guarantee that Nntp responses are framed properly (though not that they are semantically valid)

NntpConnection DOES NOT...

• Manage any of the stateful details of the connection such as server capabilities, selected group, or selected articles.
• Perform detailed parsing of responses.

For a more ergonomic client please see the NntpClient.

Usage

Please note that NNTP is a STATEFUL protocol and the Connection DOES NOT maintain any information about this state.

The command method can be used perform basic command/receive operations

For finer grained control over I/O please see the following:

• send & send_bytes for writing commands
• read_response & read_response_auto for reading responses

Buffer Management

The connection maintains several internal buffers for reading responses. These buffers may grow when reading large responses.

The buffer sizes can be tuned via ConnectionConfig, and they can be reset to their preconfigured size by calling NntpConnection::reset_buffers.

Example: Getting Capabilities

use std::time::Duration;
use brokaw::types::prelude::*;
use brokaw::types::command as cmd;
use brokaw::raw::connection::NntpConnection;

fn main() -> Result<(), Box::<dyn std::error::Error>> {
let (mut conn, init_resp) = NntpConnection::connect(
        ("news.mozilla.org", 119),
        None,
        Some(Duration::from_secs(5))
    )?;
    assert_eq!(init_resp.code(), ResponseCode::Known(Kind::PostingAllowed));
    let resp = conn.command(&cmd::Capabilities)?;
    let data_blocks = resp.data_blocks().unwrap();
    assert_eq!(&resp.code(), &ResponseCode::Known(Kind::Capabilities));

    let contains_version = data_blocks
        .lines()
        .map(|line| std::str::from_utf8(line).unwrap())
        .any(|l| l.contains("VERSION"));

    assert!(contains_version);
    Ok(())
}

Implementations

impl NntpConnection

pub fn connect(
    addr: impl ToSocketAddrs,
    config: ConnectionConfig
) -> Result<(Self, RawResponse)>

Connect to an NNTP server

pub fn with_defaults(addr: impl ToSocketAddrs) -> Result<(Self, RawResponse)>

Create an NntpConnection with the default configuration

pub fn command<C: NntpCommand>(&mut self, command: &C) -> Result<RawResponse>

Send a command to the server and read the response

This function will:

1. Block while reading the response
2. Parse the response
3. This function may allocate depending on the size of the response

pub fn command_multiline<C: NntpCommand>(
    &mut self,
    command: &C,
    is_multiline: bool
) -> Result<RawResponse>

Send a command and specify whether the response is multiline

pub fn send<C: NntpCommand>(&mut self, command: &C) -> Result<usize>

Send a command to the server, returning the number of bytes written

The caller is responsible for reading the response

pub fn send_bytes(&mut self, command: impl AsRef<[u8]>) -> Result<usize>

Send a command to the server, returning the number of bytes written

This function can be used for commands not implemented/supported by the library (e.g. LISTGROUP misc.test 3000238-3000248)

• The caller is responsible for reading the response
• The command SHOULD NOT include the CRLF terminator

pub fn read_response_auto(&mut self) -> Result<RawResponse>

Read any data from the stream into a RawResponse

This function attempts to automatically determine if the response is muliti-line based on the response code.

Note that this will not work for response codes that are not supported by Kind. If you are using extensions/commands not implemented by Brokaw, please use NntpConnection::read_response to configure multiline support manually.

pub fn read_response(
    &mut self,
    is_multiline: Option<bool>
) -> Result<RawResponse>

Read an NNTP response from the connection

Multiline Responses

If is_multiline is set to None then the connection use ResponseCode::is_multiline to determine if it should expect a multiline response. This behavior can be overridden by manually specifying Some(true) or Some(false)

pub fn stream(&self) -> &BufReader<NntpStream>

Get a ref to the underlying NntpStream

pub fn stream_mut(&mut self) -> &mut BufReader<NntpStream>

Get a mutable ref to the underlying NntpStream

This can be useful if you want to handle response parsing and/or control buffering

pub fn config(&self) -> &ConnectionConfig

Get the configuration of the connection

Trait Implementations

impl Debug for NntpConnection

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.