About

Modeling the IRC protocol using Choral.

Building

It should always be possible to build the project with the most recent version of Choral. To build the project:

1. Make sure you have the Choral libraries installed (org.choral-lang:choral and org.choral-lang:runtime).

   Choral does not yet publish its libraries to any Maven repository, so for now they have to be built from source. Choral IRC tracks Choral’s master branch so it should always compile with the latest Choral version.

   Clone the Choral repository and build and install the libraries:

   mvn install
       

2. Make sure you have the choral compiler script on your PATH and that you’ve set CHORAL_PATH.

   The script is just a wrapper that looks for the Choral standalone JAR under CHORAL_HOME and invokes it. The version of the JAR should match the version of the runtime you’ve installed.

   When building Choral from source, You can find the JAR under Choral’s dist/target, which you can use as your CHORAL_PATH.

3. Build the project:

   mvn compile
       

   We make use of pattern switch expressions and therefore require at least Java 21. Pattern switch expressions first appeared in Java 17 as a preview feature, so if you don’t have Java 21 or newer you can use an earlier version not older than Java 17. In that case you will have to adjust pom.xml to also include the --enable-preview flag, along with the specific version:

   <plugin>
       <groupId>org.apache.maven.plugins</groupId>
       <artifactId>maven-compiler-plugin</artifactId>
       ...
       <configuration>
           <source>JAVA_VERSION</source>
           <target>JAVA_VERSION</target>
           <compilerArgs>--enable-preview</compilerArgs>
       </configuration>
   </plugin>
       

   NOTE: The Java compiler only accepts --enable-preview if the source and target versions match the compiler’s own version.

Running

Run the server and the client programs separately:

./server
./client

NOTE: Java code compiled with the --enable-preview option requires passing the same option to the JVM when executing the code. The above scripts invoke the two programs through Maven, which we unconditionally provide with the option through .mvn/jvm.config, so generally no adjustments are required on your part. If you wish to execute the code in a different way but had to compile with --enable-preview, don’t forget to pass the option when executing as well.

Use the client’s textual interface to connect to the server and run some commands:

/connect localhost 8667
/nick choralbot
/user choralbot
/join #choral
/privmsg #choral Hello!
/part #choral Bye!
/quit

Interoperability

The implementation is fully binary-compatible with IRC, i.e. it respects IRC’s wire format and doesn’t perform any custom communications. Therefore, it’s possible to use the client or the server with third-party implementations.

E.g. you can connect to the IRC server using a third-party client such as Weechat, HexChat, Konversation, etc., or you can use the IRC client to connect to a third-party server, such as W3C:

/connect irc.w3.org 6667

IRC Conformance Tests

Choral IRC passes all of the basic IRC tests given by =progval/irctest=, being able to connect, choose or change a nickname, join or leave a channel, message other members and channels, and gracefully handle disconnects and messages that are too long.

NOTE: Since lots of the tests just reuse foo as the nickname, if they execute too quickly it might happen that the registration is refused by our IRC server because the nickname hasn’t yet been released and is still treated as in use.

NOTE: The pingpong.py tests hardcode My.Little.Server as the hostname.

To test, run the server:

./server My.Little.Server

Then, execute the following from the progval/irctest project’s directory:

IRCTEST_SERVER_HOSTNAME=127.0.0.1 IRCTEST_SERVER_PORT=8667 pytest --controller irctest.controllers.external_server -k "$(cat <<EOF
    not IRCv3 and \
    not labeled-response and \
    not account-tag and \
    not message-tags and \
     ((testNick or \
       testStarNick or \
       testEmptyNick or \
       testFailedNickChange or \
       testEarlyNickCollision or \
       testEmptyRealname) or \
      testPing or \
      testJoin or \
      (testPart or testBasicPart) or \
      testPrivmsg or \
      testLineAtLimit or \
      (testQuit and not Ergo))
EOF
)"