A push architecture is used in applications in which the server has to send messages / data to the client without the client having to request it. This is particularly useful for applications that require real-time data, such as chat applications or stock market applications.

However, it is difficult to achieve this with HTTP for web applications as it is primarily a request-response protocol.

WebSocket connections are a solution to this problem. They allow a persistent connection between client and server, which can be used to send messages in both directions.

This project implements a Push-Server that uses WebSockets to create a push architecture that can be used for an unlimited amount of projects.

HTTP clients - let's call them publishers - can create channels where they can later send messages in. One channel should only be used for one project, so that the messages are only sent to the clients of this project.

WebSocket clients - also called subscribers - can subscribe (or unsubscribe) to (from) an unlimited amount of channels once they've established a WebSocket connection. They'll receive all messages that are sent to the channels they're subscribed to - and only those. Publishers can also address a message to a specific list of subscribers. Only those subscribers will receive the message - and only if they've subscribed to the channel.

For further information on how to use the Push-Server, see Usage.

This project is dockerized so you can easily run it in a container. It's recommended to use the pre-built image from the GitHub container registry - however you are also free to build the image yourself. Please follow the instructions below to get started.

1. Clone the repository on the target environment

   git clone https://github.com/JensOstertag/WS-PushServer.git pushserver

2. Configure the docker-compose.yml file
   • Change the ports if you want to use different ones from 5222 and 5223
   • Àdd a custom network mode (depending on your existing setup)
3. Start the container with docker compose

   docker compose up -d

For the following examples, the server should be reachable on localhost, the WebSocket service should be available on port 5222 and the HTTP service should be available on port 5223. You can change these ports when starting the docker container, in which case you have to adjust the parameters that are used in the examples below.

Publishers can create channels and send messages to the subscribers of these channels.

POST /channel/create HTTP/1.1
Host: localhost:5223

{
  "messageType": "SERVER_ACTION",
  "action": "CREATE_CHANNEL",
  "data": {
    "channel": "channelName"
  }
}

{
  "messageType": "SERVER_ACK",
  "code": 200,
  "message": "Created",
  "data": {
    "channel": "channelName",
    "channelToken": "CHANNEL_TOKEN"
  }
}

{
  "messageType": "ERROR",
  "code": 409,
  "message": "Message",
  "data": {
    "errorDetails": "Details"
  }
}

POST /channel/ping HTTP/1.1
Host: localhost:5223

{
  "messageType": "SERVER_ACTION",
  "action": "PING_CHANNEL",
  "data": {
    "channel": "channelName",
    "channelToken": "CHANNEL_TOKEN"
  }
}

{
  "messageType": "SERVER_ACK",
  "code": 200,
  "message": "OK",
  "data": {
    "channel": "channelName",
    "channelToken": null
  }
}

{
  "messageType": "ERROR",
  "code": 0,
  "message": "Message",
  "data": {
    "errorDetails": "Details"
  }
}

POST /push HTTP/1.1
Host: localhost:5223

{
  "messageType": "SERVER_ACTION",
  "action": "PUSH_MESSAGE",
  "data": {
    "channel": "channelName",
    "channelToken": "channelToken",
    "recipients": [],
    "message": "message"
  }
}

{
  "messageType": "SERVER_ACK",
  "code": 200,
  "message": "Sent",
  "data": {
    "channel": "channelName",
    "channelToken": null
  }
}

{
  "messageType": "ERROR",
  "code": 0,
  "message": "Message",
  "data": {
    "errorDetails": "Details"
  }
}

POST /channel/delete HTTP/1.1

{
  "messageType": "SERVER_ACTION",
  "action": "DELETE_CHANNEL",
  "data": {
    "channel": "channelName",
    "channelToken": "channelToken"
  }
}

{
  "messageType": "SERVER_ACK",
  "code": 200,
  "message": "Deleted",
  "data": {
    "channel": "channelName",
    "channelToken": null
  }
}

{
  "messageType": "ERROR",
  "code": 0,
  "message": "Message",
  "data": {
    "errorDetails": "Details"
  }
}

Subscribers can subscribe to channels and receive messages that are sent to these channels.

{
  "messageType": "CLIENT_ACK",
  "code": 200,
  "message": "Connected",
  "data": {
    "uuid": "clientUuid",
    "subscribedChannels": []
  }
}

{
  "messageType": "CLIENT_ACTION",
  "action": "SUBSCRIBE",
  "data": {
    "channel": "channelName"
  }
}

{
  "messageType": "CLIENT_ACK",
  "code": 200,
  "message": "Connected",
  "data": {
    "uuid": "clientUuid",
    "subscribedChannels": [
      "channelName"
    ]
  }
}

{
  "messageType": "CLIENT_ACTION",
  "action": "UNSUBSCRIBE",
  "data": {
    "channel": "channelName"
  }
}

{
  "messageType": "CLIENT_ACK",
  "code": 200,
  "message": "Connected",
  "data": {
    "uuid": "clientUuid",
    "subscribedChannels": []
  }
}

{
  "messageType": "CLIENT_PUSH",
  "code": 200,
  "message": "Push Message",
  "data": {
    "uuid": "clientUuid",
    "subscribedChannels": [
      "channelName"
    ],
    "pushMessage": {
      "channel": "channelName",
      "message": "Message"
    }
  }
}

• Java
  • Java-WebSocket v1.5.4 - GitHub: TooTallNate/Java-WebSocket, licensed under MIT License
  • Gson v2.10.1 - GitHub: google/gson, licensed under Apache License 2.0
  • Json-Schema-Validator v1.0.87 - GitHub: networknt/json-schema-validator, licensed under Apache License 2.0
  • TestNG - GitHub: cbeust/testng, licensed under Apache License 2.0
  • Maven - GitHub: apache/maven, licensed under Apache License 2.0
• Docker
  • maven 3.8.7-openjdk-21-slim - DockerHub: maven, licensed under Apache License 2.0
  • openjdk 21-jdk-slim - DockerHub: openjdk, licensed under GPLv2
• GitHub Actions
  • actions/checkout v3 - GitHub: actions/checkout, licensed under MIT License
  • docker/login-action v1 - GitHub: docker/login-action, licensed under Apache License 2.0

This project is licensed under the MIT License.