Struct NntpClient

Source

pub struct NntpClient { /* private fields */ }

Expand description

A client that returns typed responses and provides state management

NntpClient is built on top of NntpConnection and offers several niceties:

Responses from the server are typed and semantically validated
Management of the connection state (e.g. current group, known capabilities)

In exchange for these niceties, NntpClient does not provide the low-allocation guarantees that NntpConnection does. If you are really concerned about memory management, you may want to use the NntpConnection.

Implementations§

Source §

impl NntpClient

Source

pub fn conn(&mut self) -> &mut NntpConnection

Get the raw NntpConnection for the client

§Usage

NNTP is a STATEFUL PROTOCOL and misusing the underlying connection may mess up the state in the client that owns the connection.

For example, manually sending a GROUP command would leave change the group of the connection but will not update the NntpClient’s internal record.

Caveat emptor!

Source

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

Send a command

This is useful if you want to use a command you have implemented or one that is not provided by a client method

§Example

Say we have a server that uses mode switching for whatever reason. Brokaw implements a ModeReader command but it does not provide a return type. We implement one in the following example

MOTD

use std::convert::{TryFrom, TryInto};
use brokaw::types::prelude::*;
use brokaw::types::command as cmd;

struct Motd {
    posting_allowed: bool,
    motd: String,
}

impl TryFrom<RawResponse> for Motd {
    type Error = String;

    fn try_from(resp: RawResponse) -> Result<Self, Self::Error> {
        let posting_allowed = match resp.code() {
            ResponseCode::Known(Kind::PostingAllowed) => true,
            ResponseCode::Known(Kind::PostingNotPermitted) => false,
            ResponseCode::Known(Kind::PermanentlyUnavailable) => {
                return Err("Server is gone forever".to_string());
            }
            ResponseCode::Known(Kind::TemporarilyUnavailable) => {
                return Err("Server is down?".to_string());
            }
            code => return Err(format!("Unexpected {:?}", code))
        };
        let mut motd = String::from_utf8_lossy(resp.first_line_without_code())
            .to_string();

        Ok(Motd { posting_allowed, motd })
    }
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    use brokaw::client::{NntpClient, ClientConfig};
    let mut client = ClientConfig::default()
        .connect(("news.modeswitching.notreal", 119))?;

    let resp: Motd = client.command(cmd::ModeReader)?.try_into()?;
    println!("Motd: {}", resp.motd);
    Ok(())
}

Source

pub fn config(&self) -> &ClientConfig

Get the currently selected group

Source

pub fn group(&self) -> Option<&Group>

Get the last selected group

Source

pub fn select_group(&mut self, name: impl AsRef<str>) -> Result<Group>

Select a newsgroup

Source

pub fn capabilities(&self) -> &Capabilities

The capabilities cached in the client

Source

pub fn update_capabilities(&mut self) -> Result<&Capabilities>

Retrieve updated capabilities from the server

Source

pub fn article(&mut self, article: Article) -> Result<BinaryArticle>

Retrieve an article from the server

§Text Articles

Binary articles can be converted to text using the to_text and to_text_lossy methods. Note that the former is fallible as it will validate that the body of the article is UTF-8.

use brokaw::client::NntpClient;
use brokaw::error::Result;
use brokaw::types::prelude::*;
use brokaw::types::command::Article;

fn checked_conversion(client: &mut NntpClient) -> Result<TextArticle> {
    client.article(Article::Number(42))
        .and_then(|b| b.to_text())
}

fn lossy_conversion(client: &mut NntpClient) -> Result<TextArticle> {
    client.article(Article::Number(42))
        .map(|b| b.to_text_lossy())
}