Struct Connection

pub struct Connection<R: ProtocolPacket, W: ProtocolPacket> {
    pub reader: ReadConnection<R>,
    pub writer: WriteConnection<W>,
}

A connection that can read and write packets.

Examples

Join an offline-mode server and go through the handshake.

use azalea_protocol::{
    resolver,
    connect::Connection,
    packets::{
        ClientIntention, PROTOCOL_VERSION,
        login::{
            ClientboundLoginPacket,
            serverbound_hello_packet::ServerboundHelloPacket,
            serverbound_key_packet::ServerboundKeyPacket
        },
        handshaking::client_intention_packet::ClientIntentionPacket
    }
};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let resolved_address = resolver::resolve_address(&"localhost".try_into().unwrap()).await?;
    let mut conn = Connection::new(&resolved_address).await?;

    // handshake
    conn.write(
        ClientIntentionPacket {
            protocol_version: PROTOCOL_VERSION,
            hostname: resolved_address.ip().to_string(),
            port: resolved_address.port(),
            intention: ClientIntention::Login,
        }
        .get(),
    )
    .await?;

    let mut conn = conn.login();

    // login
    conn.write(
        ServerboundHelloPacket {
            name: "bot".to_string(),
            profile_id: uuid::Uuid::nil(),
        }
        .get(),
    )
    .await?;

    let (conn, game_profile) = loop {
        let packet = conn.read().await?;
        match packet {
            ClientboundLoginPacket::Hello(p) => {
                let e = azalea_crypto::encrypt(&p.public_key, &p.challenge).unwrap();

                conn.write(
                    ServerboundKeyPacket {
                        key_bytes: e.encrypted_public_key,
                        encrypted_challenge: e.encrypted_challenge,
                    }
                    .get(),
                )
                .await?;
                conn.set_encryption_key(e.secret_key);
            }
            ClientboundLoginPacket::LoginCompression(p) => {
                conn.set_compression_threshold(p.compression_threshold);
            }
            ClientboundLoginPacket::LoginFinished(p) => {
                break (conn.configuration(), p.game_profile);
            }
            ClientboundLoginPacket::LoginDisconnect(p) => {
                eprintln!("login disconnect: {}", p.reason);
                return Err("login disconnect".into());
            }
            ClientboundLoginPacket::CustomQuery(p) => {}
            ClientboundLoginPacket::CookieRequest(_) => {}
        }
    };

    Ok(())
}

Fields

reader: ReadConnection<R>

writer: WriteConnection<W>

Implementations

impl<R, W> Connection<R, W>

where R: ProtocolPacket + Debug, W: ProtocolPacket + Debug,

pub async fn read(&mut self) -> Result<R, Box<ReadPacketError>>

Read a packet from the other side of the connection.

pub fn try_read(&mut self) -> Result<Option<R>, Box<ReadPacketError>>

Try to read a packet from the other side of the connection, or return Ok(None) if there’s no packet to read.

pub async fn write(&mut self, packet: W) -> Result<()>

Write a packet to the other side of the connection.

pub fn into_split(self) -> (ReadConnection<R>, WriteConnection<W>)

Split the reader and writer into two objects. This doesn’t allocate.

impl Connection<ClientboundHandshakePacket, ServerboundHandshakePacket>

pub async fn new(address: &SocketAddr) -> Result<Self, ConnectionError>

Create a new connection to the given address.

pub async fn new_with_proxy( address: &SocketAddr, proxy: Proxy, ) -> Result<Self, ConnectionError>

Create a new connection to the given address and Socks5 proxy. If you’re not using a proxy, use Self::new instead.

pub async fn new_from_stream(stream: TcpStream) -> Result<Self, ConnectionError>

Create a new connection from an existing stream. Useful if you want to set custom options on the stream. Otherwise, just use Self::new.

pub fn login(self) -> Connection<ClientboundLoginPacket, ServerboundLoginPacket>

Change our state from handshake to login. This is the state that is used for logging in.

pub fn status( self, ) -> Connection<ClientboundStatusPacket, ServerboundStatusPacket>

Change our state from handshake to status. This is the state that is used for pinging the server.

impl Connection<ClientboundLoginPacket, ServerboundLoginPacket>

pub fn set_compression_threshold(&mut self, threshold: i32)

Set our compression threshold, i.e. the maximum size that a packet is allowed to be without getting compressed. If you set it to less than 0 then compression gets disabled.

pub fn set_encryption_key(&mut self, key: [u8; 16])

Set the encryption key that is used to encrypt and decrypt packets. It’s the same for both reading and writing.

pub fn configuration( self, ) -> Connection<ClientboundConfigurationPacket, ServerboundConfigurationPacket>

Change our state from login to configuration. This is the state where the server sends us the registries and resource pack and stuff.

pub async fn authenticate( &self, access_token: &str, uuid: &Uuid, private_key: [u8; 16], packet: &ClientboundHelloPacket, ) -> Result<(), ClientSessionServerError>

Authenticate with Minecraft’s servers, which is required to join online-mode servers. This must happen when you get a ClientboundLoginPacket::Hello packet.

Examples

use azalea_auth::AuthResult;
use azalea_protocol::connect::Connection;
use azalea_protocol::packets::login::{
    ClientboundLoginPacket,
    serverbound_key_packet::ServerboundKeyPacket
};
use uuid::Uuid;

let AuthResult { access_token, profile } = azalea_auth::auth(
    "[email protected]",
    azalea_auth::AuthOpts::default()
).await.expect("Couldn't authenticate");

let mut conn = Connection::new(&resolved_address).await?;

// transition to the login state, in a real program we would have done a handshake first
let mut conn = conn.login();

match conn.read().await? {
    ClientboundLoginPacket::Hello(p) => {
        // tell Mojang we're joining the server & enable encryption
        let e = azalea_crypto::encrypt(&p.public_key, &p.challenge).unwrap();
        conn.authenticate(
            &access_token,
            &profile.id,
            e.secret_key,
            &p
        ).await?;
        conn.write(
            ServerboundKeyPacket {
                key_bytes: e.encrypted_public_key,
                encrypted_challenge: e.encrypted_challenge,
            }.get()
        ).await?;
        conn.set_encryption_key(e.secret_key);
    }
    _ => {}
}

impl Connection<ServerboundHandshakePacket, ClientboundHandshakePacket>

pub fn login(self) -> Connection<ServerboundLoginPacket, ClientboundLoginPacket>

Change our state from handshake to login. This is the state that is used for logging in.

pub fn status( self, ) -> Connection<ServerboundStatusPacket, ClientboundStatusPacket>

Change our state from handshake to status. This is the state that is used for pinging the server.

impl Connection<ServerboundLoginPacket, ClientboundLoginPacket>

pub fn set_compression_threshold(&mut self, threshold: i32)

Set our compression threshold, i.e. the maximum size that a packet is allowed to be without getting compressed. If you set it to less than 0 then compression gets disabled.

pub fn set_encryption_key(&mut self, key: [u8; 16])

Set the encryption key that is used to encrypt and decrypt packets. It’s the same for both reading and writing.

pub fn game(self) -> Connection<ServerboundGamePacket, ClientboundGamePacket>

Change our state from login to game. This is the state that’s used when the client is actually in the game.

pub async fn authenticate( &self, username: &str, public_key: &[u8], private_key: &[u8; 16], ip: Option<&str>, ) -> Result<GameProfile, ServerSessionServerError>

Verify connecting clients have authenticated with Minecraft’s servers. This must happen after the client sends a ServerboundLoginPacket::Key packet.

pub fn configuration( self, ) -> Connection<ServerboundConfigurationPacket, ClientboundConfigurationPacket>

Change our state back to configuration.

impl Connection<ServerboundConfigurationPacket, ClientboundConfigurationPacket>

pub fn game(self) -> Connection<ServerboundGamePacket, ClientboundGamePacket>

Change our state from configuration to game. This is the state that’s used when the client is actually in the world.

impl Connection<ClientboundConfigurationPacket, ServerboundConfigurationPacket>

pub fn game(self) -> Connection<ClientboundGamePacket, ServerboundGamePacket>

Change our state from configuration to game. This is the state that’s used when the client is actually in the world.

impl Connection<ClientboundGamePacket, ServerboundGamePacket>

pub fn configuration( self, ) -> Connection<ClientboundConfigurationPacket, ServerboundConfigurationPacket>

Change our state back to configuration.

impl<R1, W1> Connection<R1, W1>

where R1: ProtocolPacket + Debug, W1: ProtocolPacket + Debug,

pub fn from<R2, W2>(connection: Connection<R1, W1>) -> Connection<R2, W2>

where R2: ProtocolPacket + Debug, W2: ProtocolPacket + Debug,

Creates a Connection of a type from a Connection of another type. Useful for servers or custom packets.

pub fn wrap(stream: TcpStream) -> Connection<R1, W1>

Convert an existing TcpStream into a Connection. Useful for servers.

pub fn unwrap(self) -> Result<TcpStream, ReuniteError>

Convert from a Connection into a TcpStream. Useful for servers.