Turms

<p align="center"> <img height="100" src="https://raw.githubusercontent.com/turms-im/assets/9dbc34a9d78a68f9f7df2430b4066c82bf8a458f/logo/logo.svg"> </p>

简体中文

What is Turms

Turms is the most advanced open-source instant messaging engine for 100K~10M concurrent users in the world. Please refer to Turms Documentation for details.

Playground

(Version of demo servers: ghcr.io/turms-im/turms-admin:latest, ghcr.io/turms-im/turms-gateway:latest, ghcr.io/turms-im/turms-service:latest)

• turms-admin: http://playground.turms.im:6510

  Both the account and the password are: guest. (The account is allowed to query and add data, but is not allowed to update and delete data.)

• turms-gateway: http://playground.turms.im:10510 (port for WebSocket access) and http://playground.turms.im:11510 (port for TCP access)

• turms-service (Admin API in dev environment with fake data supported): http://playground.turms.im:8510

• Prometheus: http://playground.turms.im:9090; Grafana: http://playground.turms.im:3000

You can use any turms-client-(java/js/swift) implementation to send requests to turms-gateway and interact with other users.

In addition, Playground is set up automatically by just one command: ENV=dev,demo docker compose -f docker-compose.standalone.yml --profile monitoring up --force-recreate -d

Quick Start

Running the following commands to setup a minimum viable cluster (including turms-gateway, turms-service and turms-admin) and its dependent servers (MongoDB sharded cluster and Redis) automatically:

git clone --depth 1 https://github.com/turms-im/turms.git
cd turms
docker plugin install grafana/loki-docker-driver:latest --alias loki --grant-all-permissions
docker compose -f docker-compose.standalone.yml up --force-recreate

After the cluster is set up, you can visit turms-admin at http://localhost:6510, and enter the account and password (turms by default). If you log in successfully, it means that the cluster of Turms has been setup successfully.

You can also apply the Terraform modules provided by Turms to quickly purchase cloud services and set up a turms cluster (uses spot instances by default). After running terraform apply, wait for about 3~15 minutes (Alibaba Cloud ECS is slow to pull ghcr images), and then visit http://<public IP>:6510, if you can access turms-admin, it means that the turms cluster has been set up successfully.

（Note: The following commands will automatically purchase cloud services and deduct the corresponding fees from your account）

git clone --depth 1 https://github.com/turms-im/turms.git
cd turms/terraform/alicloud/playground
export ALICLOUD_ACCESS_KEY=<your_access_key>
export ALICLOUD_SECRET_KEY=<your_secret_key>
terraform init
terraform apply

Intro

The architecture of Turms depends on the fanout read design for creating inboxes (or message timelines), and Turms supports push model, pull model, and push-pull model to be aware of the changes of business data (For details, Business Data Change Awareness). Most of the other design details also come from commercial IM projects.

And compared to many projects with obsolete technology stacks, Turms is also the only open source IM solution that is based on modern architecture and modern technology and is suitable for medium to large scale applications.

In addition, architecture design is an art of trade-off. Some IM products take rich features as their slogan at the cost of no support for medium to large scale applications (they are only suitable for team communications). However, Turms takes extreme performance as the first priority and supports complete (rather than rich) IM features to support medium and large-scale applications. Please refer to Turms Schema Design and Observability for details.

When you need to compare Turms with other open source IM projects for features, you can first compare Turms with other open source IM projects based on the following features of Turms. Usually, you can find the differences between professional IM projects and amateur IM projects. In addition, under the chapter of Product Comparison, we also mentioned the shortcomings of the Turms project for your reference.

Note: The main disadvantage of the current Turms project is that it does not provide support for living/chat room. The technical implementation of the living/chat room is not difficult, but the product requirements, quality attribute requirements, and restrictive conditions are quite different from the scenarios of general social applications, so the first version of Turms does not provide support for it. In addition, Turms is also not suitable for small-scale enterprise communication scenarios. Using Turms for enterprise communication scenarios is using a sledgehammer to crack a nut, because enterprise communication emphasizes feature-rich rather than extreme performance, which is inconsistent with the goals of Turms, so their designs are also different. If you want to support enterprise communication scenarios, you need to develop based on Turms yourselves.

Business Features

1. Support a complete set of IM features. Turms supports almost all IM features supported by commercial instant messaging products and no restrictions on business features. And Turms also supports advanced features such as unwanted words filtering (using Aho-Corasick automaton with double array trie) and tiered storage for messages.
2. (Extensibility) Turms supports two approaches to extend: configuration properties and custom plugins. Of course, you can also modify the source code. For example, the plugin turms-plugin-minio based on turms-plugin is used to interact with MinIO server.
3. (Flexibility) Turms provides hundreds of configuration properties for developers to meet various requirements. And most of the properties can be updated at the cluster level when the cluster is running without performance loss.

Common Architecture Features

1. (Agility) Support updating Turms servers without the users' awareness of shutdown to support rapid iteration
2. (Scalability) The Turms server is stateless to be scaled out; Support multi-active across data centers
3. (Deployability) Support container deployment to facilitate integration (CI/CD) with cloud services. Turms provides three solutions for container deployment out of the box: Docker image, Docker compose file, and Terraform module
4. (Observability) Support relatively complete features of observability for business analysis and troubleshoot
5. (Scalability) Support medium to large scale instant messaging applications, and there is no need to refactor even if the application becomes large from medium-scale (There is still a lot of optimization work to be done for large applications, but Turms servers are easy to upgrade)
6. (Security) Support API throttling and global user/IP blocklist to resist most CC attacks
7. (Simplicity) The Turms architecture is lightweight, which makes Turms easy to learn and redevelop. Please refer to Turms Architecture Design for details)
8. Turms depends on the MongoDB sharded cluster to support request routing (such as read-write separation) and tiered storage for medium to large scale applications

Other Features

1. Observable system (Please refer to Observability for details)

   • Log (for events): Turms provides three types of logs: monitoring log, business log, and statistics log

   • Metrics (for aggregable data). It reflects the real-time status of the system and business data

   • Tracing

   Note that the Turms server will provide more monitoring features that can be implemented efficiently as much as possible, but will not provide some common features that have a great impact on performance and are more suitable for third-party services to provide (such as DAU). For this kind of extended feature, you can implement them by offline or real-time analysis of the logs or metrics of Turms servers.

2. Extreme performance We always try to archive extreme performance in the implementation of all business workflows. Please refer to the source code for details.

• Network
  • I/O: The Turms server is a reactive application. All network I/O operations (e.g. database call, Redis call, service discovery call, RPC) are based on Netty to achieve non-blocking I/O. Therefore, the Turms server can make full use of system resources (while traditional servers can't)
  • Encoding: Protobuf is used to encode the traffic data between Turms servers and turms clients; Custom encoding without any redundant data is used to encode the RPC requests and responses between Turms servers to ensure extreme efficiency
• Thread
  • The Turms server has an excellent thread model, and its peak thread number is constant, which is independent of the number of online users and the number of requests. Since the default number of threads in the access layer of the Turms server is the same as that of the CPU processors, the Turms server can make full use of the CPU cache, and greatly reduce the cost of thread context switching and thread contention compared with traditional servers
  • During business logic processing, there are almost no locks, only CAS operations
• Memory
  • The Turms server allocates heap or direct memory smartly according to its usage to reduce the memory footprint
  • The Turms server refactors parts of MongoDB/Redis client dependencies to ensure that there is no redundant memory allocation in the Turms server, which greatly improves the effective use of memory
• Cache: The Turms server