irc

package module
v1.0.6 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 3, 2024 License: BSD-3-Clause Imports: 22 Imported by: 0

README

Important Update: Handling ERROR Events as Disconnects

In the latest release of our IRC library, we've introduced a new feature that changes how the library handles ERROR events received from the IRC server.

New Feature: HandleErrorAsDisconnect Flag

We've added a new boolean flag to the Connection struct called HandleErrorAsDisconnect. This flag allows you to control how the library reacts when an ERROR event is received from the server.

  • Default Value in Latest Release: true
  • Behavior When true:
    • The library treats ERROR events as connection errors.
    • It does not automatically attempt to reconnect after receiving an ERROR.
    • You have the flexibility to implement your own reconnection logic in response to ERROR events.
  • Behavior When false:
    • The library behaves as in previous releases.
    • It may automatically attempt to reconnect after an ERROR, potentially leading to reconnection loops.

Impact on Existing Bots and Applications

Since the default value is now set to true, existing bots and applications using this library may experience changes in behavior:

  • If your application relies on automatic reconnection after an ERROR:
    • You'll need to explicitly set HandleErrorAsDisconnect to false in your code to retain the previous behavior.
    • Alternatively, consider using the previous release of the library.

How to Set the HandleErrorAsDisconnect Flag

To adjust the behavior of your application, set the HandleErrorAsDisconnect flag when initializing your IRC connection:

irccon := irc.IRC("nick", "user")
// Set to false to retain previous behavior
irccon.HandleErrorAsDisconnect = false

Recommendation for Users

  • For Users Who Want the New Behavior:

    • No action is needed. The library will, by default, treat ERROR events as disconnects and will not automatically reconnect.
    • Implement your own logic to handle reconnections if desired.

  • For Users Who Prefer the Previous Behavior:

    • Set HandleErrorAsDisconnect to false in your code.
    • Alternatively, you can continue using the previous release of the library.

Example: Custom Reconnection Logic

If you choose to handle reconnections manually, you can add a callback for the ERROR event:

irccon := irc.IRC("nick", "user")
irccon.HandleErrorAsDisconnect = true

irccon.AddCallback("ERROR", func(e *irc.Event) {
    irccon.Log.Printf("Received ERROR: %s", e.Message())
    // Implement your reconnection logic here
    time.Sleep(30 * time.Second)
    err := irccon.Reconnect()
    if err != nil {
        irccon.Log.Printf("Reconnect failed: %s", err)
    }
})

Summary

  • New Feature: HandleErrorAsDisconnect flag added.
  • Default Behavior Changed: The library now treats ERROR events as disconnects by default.
  • Action Required: If you rely on the old behavior, set HandleErrorAsDisconnect to false or use the previous release.

We believe this change will give developers better control over how their applications handle server ERROR events, preventing unwanted reconnection loops and allowing for more robust error handling.

If you have any questions or need assistance with this update, please feel free to reach out.

go-ircevo

go-ircevo is an evolved and extended version of the original go-ircevent library by Thomas Jager. This library provides an enhanced framework for interacting with IRC servers, supporting additional features like DCC, SASL authentication, proxy support, and more.

Originally, this library started as a fork of go-ircevent, but it has been significantly expanded to meet the needs I encountered while developing my own IRC bot. Due to the number of changes and the direction I've taken, I'm continuing this project under a new name, go-ircevo. Nevertheless, I intend to keep contributing important features back to the original go-ircevent fork, ensuring backward compatibility so that they can be integrated into the original library if desired.

Features

  • Support for direct client-to-client (DCC) communication
  • Enhanced IRC command handling
  • SASL authentication support
  • Proxy integration for IRC connections
  • Extended message handling
  • Compatible with the original go-ircevent API for easy migration

Installation

go get github.com/kofany/go-ircevo

Usage

Here is an example of how to use go-ircevo to connect to an IRC server:

package main

import (
    "log"
    "github.com/kofany/go-ircevo"
)

func main() {
    conn := ircevo.IRC("nickname", "username")
    err := conn.Connect("irc.freenode.net:6667")
    if err != nil {
        log.Fatal(err)
    }

    conn.AddCallback("001", func(e *ircevo.Event) {
        conn.Join("#channel")
    })

    conn.Loop()
}

License

This project is licensed under the BSD license, based on the original go-ircevent library by Thomas Jager. Please see the LICENSE file for more details.

Documentation

Overview

Copyright (c) 2024 Jerzy Dąbrowski Based on original work by Thomas Jager, 2009. All rights reserved.

This project is a fork of the original go-ircevent library created by Thomas Jager. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  • Redistributions of source code must retain the above copyright notice, this list of conditions, and the following disclaimer.
  • Redistributions in binary form must reproduce the above copyright notice, this list of conditions, and the following disclaimer in the documentation and/or other materials provided with the distribution.
  • Neither the name of the original authors nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Copyright (c) 2024 Jerzy Dąbrowski Based on original work by Thomas Jager, 2009. All rights reserved.

This project is a fork of the original go-ircevent library created by Thomas Jager. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  • Redistributions of source code must retain the above copyright notice, this list of conditions, and the following disclaimer.
  • Redistributions in binary form must reproduce the above copyright notice, this list of conditions, and the following disclaimer in the documentation and/or other materials provided with the distribution.
  • Neither the name of the original authors nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Index

Constants

View Source 
const CAP_TIMEOUT = time.Second * 15
View Source 
const (
	VERSION = "go-ircevent v2.1+myip"
)

Variables

View Source 
var ErrDisconnected = errors.New("Disconnect Called")

Functions

This section is empty.

Types

type CallbackID 

type CallbackID struct {
	EventCode string
	ID        int
}

CallbackID is a tuple type for uniquely identifying callbacks.

type Connection 

type Connection struct {
	sync.Mutex
	sync.WaitGroup
	Debug            bool
	Error            chan error
	WebIRC           string
	Password         string
	UseTLS           bool
	UseSASL          bool
	RequestCaps      []string
	AcknowledgedCaps []string
	SASLLogin        string
	SASLPassword     string
	SASLMech         string
	TLSConfig        *tls.Config
	Version          string
	Timeout          time.Duration
	CallbackTimeout  time.Duration
	PingFreq         time.Duration
	KeepAlive        time.Duration
	Server           string
	Encoding         encoding.Encoding
	ProxyConfig      *ProxyConfig

	RealName string // The real name we want to display.

	QuitMessage string

	VerboseCallbackHandler bool
	Log                    *log.Logger

	DCCManager              *DCCManager // DCC chat support
	HandleErrorAsDisconnect bool        // Fix reconnection loop after ERROR event if user have own reconnect implementation
	// contains filtered or unexported fields
}

Connection represents an IRC connection.

func IRC 

func IRC(nick, user string) *Connection

Create a connection with the (publicly visible) nickname and username. The nickname is later used to address the user. Returns nil if nick or user are empty.

func (*Connection) Action 

func (irc *Connection) Action(target, message string)

Send (action) message to a target (channel or nickname). No clear RFC on this one...

func (*Connection) Actionf 

func (irc *Connection) Actionf(target, format string, a ...interface{})

Send formatted (action) message to a target (channel or nickname).

func (*Connection) AddCallback 

func (irc *Connection) AddCallback(eventcode string, callback func(*Event)) int

AddCallback registers a callback to a connection and event code. A callback is a function which takes only an Event pointer as a parameter. Valid event codes are all IRC/CTCP commands and error/response codes. To register a callback for all events, pass "*" as the event code. This function returns the ID of the registered callback for later management.

func (*Connection) ClearCallback 

func (irc *Connection) ClearCallback(eventcode string) bool

ClearCallback removes all callbacks from a given event code. It returns true if the given event code is found and cleared.

func (*Connection) CloseDCCChat 

func (irc *Connection) CloseDCCChat(nick string) error

CloseDCCChat zamyka połączenie DCC CHAT z określonym nickiem

func (*Connection) Connect 

func (irc *Connection) Connect(server string) error

Connect to a given server using the current connection configuration. This function also takes care of identification if a password is provided. RFC 1459 details: https://tools.ietf.org/html/rfc1459#section-4.1

func (*Connection) Connected 

func (irc *Connection) Connected() bool

Returns true if the connection is connected to an IRC server.

func (*Connection) Disconnect 

func (irc *Connection) Disconnect()

A disconnect sends all buffered messages (if possible), stops all goroutines and then closes the socket.

func (*Connection) ErrorChan 

func (irc *Connection) ErrorChan() chan error

func (*Connection) GetDCCMessage 

func (irc *Connection) GetDCCMessage(nick string) (string, error)

func (*Connection) GetNick 

func (irc *Connection) GetNick() string

Determine nick currently used with the connection.

func (*Connection) InitiateDCCChat 

func (irc *Connection) InitiateDCCChat(target string) error

func (*Connection) IsDCCChatActive 

func (irc *Connection) IsDCCChatActive(nick string) bool

IsDCCChatActive sprawdza, czy istnieje aktywne połączenie DCC CHAT z danym nickiem

func (*Connection) IsFullyConnected 

func (irc *Connection) IsFullyConnected() bool

func (*Connection) Join 

func (irc *Connection) Join(channel string)

Use the connection to join a given channel. RFC 1459 details: https://tools.ietf.org/html/rfc1459#section-4.2.1

func (*Connection) Kick 

func (irc *Connection) Kick(user, channel, msg string)

Kick <user> from <channel> with <msg>. For no message, pass empty string ("")

func (*Connection) ListActiveDCCChats 

func (irc *Connection) ListActiveDCCChats() []string

ListActiveDCCChats zwraca listę nicków, z którymi mamy aktywne połączenia DCC CHAT

func (*Connection) Loop 

func (irc *Connection) Loop()

Main loop to control the connection.

func (*Connection) Mode 

func (irc *Connection) Mode(target string, modestring ...string)

Set different modes for a target (channel or nickname). RFC 1459 details: https://tools.ietf.org/html/rfc1459#section-4.2.3

func (*Connection) MultiKick 

func (irc *Connection) MultiKick(users []string, channel string, msg string)

Kick all <users> from <channel> with <msg>. For no message, pass empty string ("")

func (*Connection) Nick 

func (irc *Connection) Nick(n string)

Set (new) nickname. RFC 1459 details: https://tools.ietf.org/html/rfc1459#section-4.1.2

func (*Connection) Notice 

func (irc *Connection) Notice(target, message string)

Send a notification to a nickname. This is similar to Privmsg but must not receive replies. RFC 1459 details: https://tools.ietf.org/html/rfc1459#section-4.4.2

func (*Connection) Noticef 

func (irc *Connection) Noticef(target, format string, a ...interface{})

Send a formatted notification to a nickname. RFC 1459 details: https://tools.ietf.org/html/rfc1459#section-4.4.2

func (*Connection) Part 

func (irc *Connection) Part(channel string)

Leave a given channel. RFC 1459 details: https://tools.ietf.org/html/rfc1459#section-4.2.2

func (*Connection) Privmsg 

func (irc *Connection) Privmsg(target, message string)

Send (private) message to a target (channel or nickname). RFC 1459 details: https://tools.ietf.org/html/rfc1459#section-4.4.1

func (*Connection) Privmsgf 

func (irc *Connection) Privmsgf(target, format string, a ...interface{})

Send formatted string to specified target (channel or nickname).

func (*Connection) Quit 

func (irc *Connection) Quit()

Quit the current connection and disconnect from the server RFC 1459 details: https://tools.ietf.org/html/rfc1459#section-4.1.6

func (*Connection) Reconnect 

func (irc *Connection) Reconnect() error

Reconnect to a server using the current connection.

func (*Connection) RemoveCallback 

func (irc *Connection) RemoveCallback(eventcode string, i int) bool

RemoveCallback removes callback i (ID) from the given event code. This function returns true upon success, false if any error occurs.

func (*Connection) ReplaceCallback 

func (irc *Connection) ReplaceCallback(eventcode string, i int, callback func(*Event))

ReplaceCallback replaces callback i (ID) associated with a given event code with a new callback function.

func (*Connection) RunCallbacks 

func (irc *Connection) RunCallbacks(event *Event)

RunCallbacks executes all callbacks associated with a given event.

func (*Connection) SendDCCMessage 

func (irc *Connection) SendDCCMessage(nick, message string) error

func (*Connection) SendRaw 

func (irc *Connection) SendRaw(message string)

Send raw string.

func (*Connection) SendRawf 

func (irc *Connection) SendRawf(format string, a ...interface{})

Send raw formatted string.

func (*Connection) SetDCCChatTimeout 

func (irc *Connection) SetDCCChatTimeout(timeout time.Duration)

SetDCCChatTimeout ustawia timeout dla połączeń DCC CHAT

func (*Connection) SetLocalIP 

func (irc *Connection) SetLocalIP(ip string)

SetLocalIP sets the local IP address to bind when connecting. This allows the client to specify which local interface/IP to use.

func (*Connection) SetProxy 

func (irc *Connection) SetProxy(proxyType, address, username, password string)

func (*Connection) Who 

func (irc *Connection) Who(nick string)

Query information about a given nickname in the server. RFC 1459 details: https://tools.ietf.org/html/rfc1459#section-4.5.1

func (*Connection) Whois 

func (irc *Connection) Whois(nick string)

Query information about a particular nickname. RFC 1459: https://tools.ietf.org/html/rfc1459#section-4.5.2

type DCCChat 

type DCCChat struct {
	Nick     string
	Conn     net.Conn
	Incoming chan string
	Outgoing chan string
	// contains filtered or unexported fields
}

DCCChat reprezentuje pojedyncze połączenie DCC CHAT

type DCCManager 

type DCCManager struct {
	// contains filtered or unexported fields
}

DCCManager zarządza wszystkimi połączeniami DCC

func NewDCCManager 

func NewDCCManager() *DCCManager

NewDCCManager tworzy nowy menedżer DCC

type Event 

type Event struct {
	Code       string
	Raw        string
	Nick       string //<nick>
	Host       string //<nick>!<usr>@<host>
	Source     string //<host>
	User       string //<usr>
	Arguments  []string
	Tags       map[string]string
	Connection *Connection
	Ctx        context.Context
}

Event represents an IRC event.

func (*Event) Message 

func (e *Event) Message() string

Message retrieves the last message from Event arguments. This function leaves the arguments untouched and returns an empty string if there are none.

func (*Event) MessageWithoutFormat 

func (e *Event) MessageWithoutFormat() string

MessageWithoutFormat retrieves the last message from Event arguments, but without IRC formatting (e.g., colors). This function leaves the arguments untouched and returns an empty string if there are none.

type ProxyConfig 

type ProxyConfig struct {
	Type     string // "socks5", "http", etc....
	Address  string
	Username string
	Password string
}

type SASLResult 

type SASLResult struct {
	Failed bool
	Err    error
}

Source Files

View all Source files

Directories

Path Synopsis
examples
simple
simple-tor.go

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.