{"id":20027006,"url":"https://github.com/defective4/trivialpacketprotocol","last_synced_at":"2026-05-17T00:50:53.953Z","repository":{"id":252804433,"uuid":"841508675","full_name":"Defective4/TrivialPacketProtocol","owner":"Defective4","description":"A client - server library for sending data in the form of packets over network","archived":false,"fork":false,"pushed_at":"2024-08-18T07:05:18.000Z","size":177,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-02-27T08:13:52.848Z","etag":null,"topics":["io","java","library","maven","network","packet"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Defective4.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-08-12T14:45:51.000Z","updated_at":"2024-08-19T14:38:31.000Z","dependencies_parsed_at":"2024-08-18T08:23:53.438Z","dependency_job_id":null,"html_url":"https://github.com/Defective4/TrivialPacketProtocol","commit_stats":null,"previous_names":["defective4/trivialpacketprotocol"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/Defective4/TrivialPacketProtocol","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Defective4%2FTrivialPacketProtocol","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Defective4%2FTrivialPacketProtocol/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Defective4%2FTrivialPacketProtocol/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Defective4%2FTrivialPacketProtocol/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Defective4","download_url":"https://codeload.github.com/Defective4/TrivialPacketProtocol/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Defective4%2FTrivialPacketProtocol/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33124141,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-16T18:38:32.183Z","status":"ssl_error","status_checked_at":"2026-05-16T18:38:29.903Z","response_time":115,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["io","java","library","maven","network","packet"],"created_at":"2024-11-13T09:08:46.349Z","updated_at":"2026-05-17T00:50:53.934Z","avatar_url":"https://github.com/Defective4.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Trivial Packet Protocol\n[About](#about) | [Installation](#installation) | [Usage](#usage)\n\n## About\nTrivial Packet Protocol is a client and server library, allowing you to send binary data in the form of packets over network.  \nIt makes it easier to maintain a continuous stream between two or more pieces of software running on different machines.  \nThe library is designed to allow you to design a network flow, where you use string commands to occasionally request data from the server and listen for a binary response.\n\n## Library features\n- [x] 🪶 Simple, lightweight client - server structure\n- [x] 📦 Zero required dependencies\n- [x] 🔑 SSL support, using a Certificate and a Private Key\n- [x] 🧩 Expandable - You can register and use your own packets\n- [x] 📎 Secure - Requires a token on both ends before accepting any packets\n\n## Use cases\nThis library is perfect for situations, where you need to occasionally request data from a server without opening a new connection every single time.  \nTrivial Packet Protocol allows you to open and maintain a constant, protected, and encrypted connection between client(s) and a server.\n\n## How does it work?\nTrivial Packet Protocol uses **packets**. Each time one party wants to send a request, it sends a packet to the other. Likewise if the other party wants to respond to a request, it sends back another packet.  \nEach party can **send** and **listen** for packets.\nSending and receiving is done **independently**, meaning you can both send and listen for packets at the same time\\*, instead of following a strict request - response flow.\n\n\\* keep in mind, that while the library can be used concurrently to some extent, it's not guaranteed to be thread safe!\n\n## The Protocol\nThe client starts by sending an `Authentication` packet with user-supplied token, which acts like a plain-text password.  \nThe server then compares the received token with its own, and if it matches it responds with `Authentication Success` packet, otherwise it disconnects the client with a `Disconnect` packet.  \nAfter authentication is finished, both the server and the client are put in the reading mode.  \nBoth parties can send any packets at any time, and the other party is required to handle it correctly, but received packets don't need to be acknowledged.  \nIn default library implementation the client sends a `Ping` packet every 15 seconds and expects the server to reply to it in the near future.\nIf the client does not receive a `Ping` response before sending the next `Ping` packet, it disconnects with a \"Timed Out\" message.\n\n![drawing1](img/drawing1.png)\n\n## Requirements\nCurrently the only requirement to use the library is Java 17\n\n## Installation\n### From Maven\nAdd this to the `dependencies` section of your `pom.xml`:\n**Server**\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003eio.github.defective4.trivialpacket\u003c/groupId\u003e\n    \u003cartifactId\u003epacket-server\u003c/artifactId\u003e\n    \u003cversion\u003e{latest version}\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n**Client**\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003eio.github.defective4.trivialpacket\u003c/groupId\u003e\n    \u003cartifactId\u003epacket-client\u003c/artifactId\u003e\n    \u003cversion\u003e{latest version}\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\nWhere `{latest version}` is:  \n  \n![Maven Central Version](https://img.shields.io/maven-central/v/io.github.defective4.trivialpacket/trivial-packet-protocol)\n\n### From releases\nYou can download the common, client and/or server jars from [Releases](https://github.com/Defective4/TrivialPacketProtocol/releases/latest) \npage and include them manually in your build path\n\n### From source\n0. Make sure you have `git` and `maven` installed\n1. `git clone https://github.com/Defective4/TrivialPacketProtocol.git`\n2. `cd TrivialPacketProtocol`\n3. `mvn clean package`\n\nThe compiled binaries will now be available in:\n- Client: `packet-client/target`\n- Server: `packet-server/target`  \n\nJust include them in your classpath and you are good to go!\n\n## Usage\nFor more examples see [Examples](examples/src/main/java/io/github/defective4/trivialpacket/examples/).  \n\nSimple client and server with an example command:\n```java\npublic static void main(String[] args) {\n    int port = 8080;\n    String serverToken = \"TOKEN\";\n    String clientToken = \"TOKEN\"; // You have to keep the two tokens the same for authorization to work\n\n    new Thread(() -\u003e {\n        try (CmdServer server = new CmdServer(\"localhost\", port, serverToken.toCharArray())) {\n            server.addListener(new ServerAdapter() {\n\n                @Override\n                public void clientDisconnected(ClientConnection connection) throws Exception {\n                    server.close();\n                }\n\n                @Override\n                public void commandReceived(ClientConnection connection, String command, String[] args)\n                        throws Exception {\n                    connection\n                            .respond(String\n                                    .format(\"Command: %s, Arguments: [%s]\", command, String.join(\", \", args))\n                                    .getBytes());\n                }\n            });\n\n            server.start();\n        } catch (Exception e) {\n            e.printStackTrace();\n        }\n    }).start();\n\n    try (CmdClient client = new CmdClient(\"localhost\", port, clientToken.toCharArray())) {\n        Thread.sleep(500);\n        client.addListener(new ClientAdapter() {\n\n            @Override\n            public void authorized() throws Exception {\n                client.sendCommand(\"echo\", \"Hello\", \"World\");\n            }\n\n            @Override\n            public void responseReceived(byte[] data) throws Exception {\n                System.out.println(new String(data));\n                client.disconnect(\"Disconnected\");\n            }\n\n        });\n        client.connect();\n    } catch (Exception e2) {\n        e2.printStackTrace();\n    }\n}\n```\n\n## Defining custom packets\nSee [CustomPacketExample.java](examples/src/main/java/io/github/defective4/trivialpacket/examples/CustomPacketExample.java) for a practical example. \n\n### Step 0 - Setting up client and server projects\nCreate two separate projects, one with `packet-client` dependency, and one with `packet-server`.\n\n### Step 1 - Creating a custom Packet class\nWe will create a class that sends a single string from one end to another.  \n\nWrite the following class:\n```java\npackage io.github.defective4.trivialpacket.common.packet;\n\npublic static class ExamplePacket extends Packet {\n\n    private final String string;\n\n    public ExamplePacket(String string) {\n        this.string = string;\n    }\n\n    public String getString() {\n        return string;\n    }\n\n    @Override\n    protected void writePacketData(DataOutputStream str) throws IOException {\n        str.write(string.getBytes());\n    }\n}\n```\nand save it in **both** of your projects.  \nNotice the `writePacketData` method. It writes our packet's data to a buffer, that later gets sent to the second end.\n\n### Step 2 - Creating a factory for our packet\nWe need to create a packet factory, that will convert received `byte[]` data to fields used by our packet.\n```java\npublic static final PacketFactory\u003cExamplePacket\u003e FACTORY = new PacketFactory\u003c\u003e(ExamplePacket.class) {\n\n    @Override\n    protected ExamplePacket createPacket(byte[] data) throws Exception {\n        return new ExamplePacket(new String(data));\n    }\n};\n```\n\n### Step 3 - Registering the factory\nTo use the packet we need to register it in the `PacketFactoryRegistry`.  \nHere's an example code:\n```java\nPacketFactoryRegistry.registerPacketFactory(6, FACTORY);\n```\ndo it in both of your projects. \nNotice the `6` - it's the **unique ID** of our packet. It can be anything, as long as it does not clash with any other packets, including the built-in ones.  \nBuilt-in packets occupy the ID range from 0 to 5 at the time of writing.  \nThe ID itself does not matter for us, but it has to be kept the same between the server and the client.\n\n### Step 4 - Using the packet\nCode for the server:\n```java\ntry(CmdServer server = new CmdServer(\"localhost\", 8083, null)) {\n    server.addListener(new ServerAdapter() {\n\n        @Override\n        public void customPacketReceived(ClientConnection connection, Packet packet) throws Exception {\n            System.out.println(\"Received custom packet: \" + packet.getClass());\n            if (packet instanceof ExamplePacket example) {\n                System.out.println(example.getString());\n                connection.disconnect(\"Closed\");\n                server.close();\n            }\n        }\n\n    });\n\n    server.start();\n}\n```\n\nCode for the client:\n```java\ntry (CmdClient client = new CmdClient(\"localhost\", 8083, null)) {\n    client.addListener(new ClientAdapter() {\n\n        @Override\n        public void authorized() throws Exception {\n            client.sendPacket(new ExamplePacket(\"Test String\"));\n        }\n\n    });\n    client.connect();\n}\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdefective4%2Ftrivialpacketprotocol","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdefective4%2Ftrivialpacketprotocol","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdefective4%2Ftrivialpacketprotocol/lists"}