Developement guide

Overview
Getting the source code
Installing dependencies
Installing an IRC daemon
Starting the application
Running tests
Secure connection
Building production assets
Directory structure
Convos frontend
Convos core
API
Contribute

Overview

This guide is for people who want to hack on Convos.

Not familiar with Perl? That's fine: Half of Convos is JavaScript and CSS, so you can modify the frontend using web knowledge. It is however helpful if you are familiar with git, Mojolicious and basic Perl tools, such as prove and cpanm.

The JavaScript is compiled using rollupjs and the JavaScript dependency tree is maintained using npm.

Getting the source code

The first step is to clone the Convos repository. You can either do this directly on github or by running the command below:

git clone https://github.com/convos-chat/convos.git

The command above will create a "convos" directory in the current working directory. The following steps need to be run from the project root, meaning you should cd ./convos first.

Installing dependencies

Once you have the source code you should install the dependencies:

npm i
./script/convos install --develop

--develop will install dependencies which is only required if you want to make changes to the files in the assets/ directory. Note that the dependencies are installed in local/lib/. If you want to install them globally or in your $HOME/perl5 directy, then use one of these command instead:

./script/cpanm --installdeps --sudo .
./script/cpanm --installdeps .

If you are on macOS, you might have to install Perl and some other utilities using homebrew:

brew install coreutils perl openssl

Installing an IRC daemon

It is highly suggested that you install an IRC daemon, since many networks will ban you if you reconnect too often. Any IRC compatible server will work, but ergo is a modern and very simple IRC server to install.

Please ask in #convos on irc.libera.chat:6697 if you want to use the demo IRC server instead of installing your own.

Starting the application

The basics of getting the application running in development mode is the command below:

./script/convos dev

The command above is the same as:

CONVOS_LOG_LEVEL=trace script/convos webpack \
  -w lib -w public/convos-api.json -w templates

CONVOS_LOG_LEVEL will print extra low level debug information to STDERR, which is useful to discover bugs. The -w switch is for watching different files and directories for changes and reload the web server automatically.

Running tests

Convos has GitHub workflows set up to run automatic tests when pushing a commit. These tests can also be run locally:

# Run all Perl tests (API, Core, …)
# (t/plugin-bot*t will be skipped without TEST_BOT=1)
TEST_BOT=1 prove -l

# Run a single Perl test, with verbose output
prove -vl t/irc-commands.t

# Run automated frontend tests in a browser
TEST_SELENIUM=1 prove -l t/selenium-*t

# Run all JavaScript tests
npm run test

# Run a single test and watch for changes. Useful when developing
npm run test -- --watch __tests__/md.js

Secure connection

Running convos dev will automatically pick up any certificated files in the root of your project. This can be useful if you want to work on some features that require "https". A self-signed certificate is often not enough, so we suggest using mkcert to set up local development certificates.

After you have installed mkcert you can simply run the following commands to get a secure connection:

mkcert localhost
./script/convos dev

The default address for the secure server will be https://localhost:3443/, but you can change that:

./script/convos dev --listen https://localhost:8443

Building production assets

The command below will create production assets, which will be used when you start the production version of Convos:

./script/convos build

Directory structure

./assets/

The assets directory contains all JavaScript and Sass files, which will be used to generate the public files. The conversion is done with Mojolicious::Plugin::Webpack.
./cpanfile

The cpanfile is used to document all the requirements, while the Makefile.PL file is generated from the content of the cpanfile.
./lib/

The lib directory contains all the Perl source code.
./public

The public directory contains fonts and images which can be downloaded through the Convos web server.
./script

The script directory contains the main application file (convos) and helper scripts. The important part here is that every file which has the executable bit set will be part of the final CPAN distribution.
./t

The t directory contains test files for the Perl code.
./__tests__

The tests directory contains test files for the JavaScript code.

Convos frontend

                .------.
            ____| Core |
.--------._/    '------'
| Convos |
'--------'    .-------------.
      \_______| Controllers |
              '-------------'

The frontend contains of a single template. The rest of the frontend consist of a JavaScript application, powered by Svelte. This application gets its data from a OpenAPI powered JSON API with a thin logical layer inside the controllers:

The main layout for the Svelte powered frontend is /assets/App.svelte and the routes are set up in /assets/routes.js.

Convos core

             .---------.
          ___| Backend |
.------._/   '---------'
| Core |
'------   .------.  .-------------.  .--------------.
    \_____| User |__| Connections |__| Conversation |
          '------'  '-------------'  '--------------'

Convos::Core is the heart of Convos. The core takes care of connections, conversations can persist to a backend and provide hooks for plugins.

The design makes Convos a multi-user application, that can persist to any backend (memory, file storage, redis, ...) and connect to any chat server, as well as keeping any number of conversations active.

The way the backend is hooked into the rest of the object graph is by events. Any user, connection or conversation can emit new events that the Backend can choose to persist to storage. The default backend is a file-based backend, which enables Convos to be started without any external database.

API

Convos has an OpenAPI powered REST API. The specification is used to both generate Perl code for validation, and to generate documentation. Resources:

TODO: Need to document the WebSocket API as well.

Contribute

Any contribution is more than welcome! Examples: If you find typos on this web page or find something annoying, then please tell us.

We welcome pull requests, but any form of patches are better than nothing. The pull request does not need to be complete either, but it is more likely to get merged if it includes tests and documentation updates.

Check out the issues for open issues. Some of the issues are put into planned milestones, but any of the backlog issues are for grabs at any time.