https://github.com/weavejester/teensyp
https://github.com/weavejester/teensyp
Last synced: 3 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/weavejester/teensyp
- Owner: weavejester
- License: other
- Created: 2025-07-09T13:35:54.000Z (6 months ago)
- Default Branch: master
- Last Pushed: 2025-07-22T00:00:55.000Z (6 months ago)
- Last Synced: 2025-10-02T10:52:22.950Z (3 months ago)
- Language: Clojure
- Size: 107 KB
- Stars: 19
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# TeensyP [](https://github.com/weavejester/teensyp/actions/workflows/test.yml)
A small, zero-dependency Clojure TCP server that uses Java NIO.
## Installation
Add the following dependency to your deps.edn file:
dev.weavejester/teensyp {:mvn/version "0.3.0"}
Or to your Leiningen project file:
[dev.weavejester/teensyp "0.3.0"]
## Usage
At minimum, TeensyP requires a port to listen on and a handler function:
```clojure
(require '[teensyp.server :as tcp])
(tcp/start-server {:port 3000, :handler demo-handler})
```
The handler function has three arities, and defines how the server
behaves.
```clojure
(import 'java.nio.ByteBuffer)
(defn demo-handler
([write]
;; With 1 argument, we can write ByteBuffers via the write function.
;; The return value is the channel's state.
{:read-bytes 0})
([state ^ByteBuffer buffer write]
;; With 3 arguments, we handle read data stored in a ByteBuffer. We
;; can update the channel's state by returning a new value, and write
;; to the output channel with the write function.
(update state :read-bytes + (.remaining buffer)))
([state exception]
;; With 2 arguments, we have the channel closing. If it closed due to an
;; exception, that exception is passed as the second argument, otherwise it
;; will be nil.
(println "Total bytes:" (:read-bytes state))
))
```
The handler maintains a `state`, which can be any Clojure data
structure, but is usually a map. This state is unique to the channel,
and is updated each time the channel is read from by the 3-arity form of
the handler.
### Writes
The `write` function accepts a single `ByteBuffer` argument, or one of
three special marker objects:
- `teensyp.server/CLOSE` - closes the channel
- `teensyp.server/PAUSE-READS` - pause reads until resumed
- `teensyp.server/RESUME-READS` - resume reads
You may also specify a second argument to `write`. This is a zero
argument callback function that will be called when the write completes.
### Guarantees
TeensyP makes several guarantees that apply per-channel:
- The 1-arity accept is always called first.
- The 2-arity close is always called last.
- The current handler call for the channel must finish before the next
can begin.
- The write queue queue must be empty before the handler is called.
### Server Options
The `start-server` function takes a number of options:
| Key | Description | Mandatory | Default |
|----------------------|-------------------------------------------------|-----------|---------|
| `:executor` | An `ExecutorService` to use for handler calls | | |
| `:handler` | The handler function | Yes | |
| `:port` | The port number to listen on | Yes | |
| `:read-buffer-size` | The size in bytes of the channel read buffer | | 8K |
| `:write-buffer-size` | The size in bytes of the channel write buffer | | 32K |
| `:write-queue-size` | The maximum number of writes that can be queued | | 64 |
## Documentation
- [API Documentation](https://weavejester.github.io/teensyp)
## License
Copyright © 2025 James Reeves
This program and the accompanying materials are made available under the
terms of the Eclipse Public License 2.0 which is available at
http://www.eclipse.org/legal/epl-2.0.
This Source Code may also be made available under the following Secondary
Licenses when the conditions for such availability set forth in the Eclipse
Public License, v. 2.0 are satisfied: GNU General Public License as published by
the Free Software Foundation, either version 2 of the License, or (at your
option) any later version, with the GNU Classpath Exception which is available
at https://www.gnu.org/software/classpath/license.html.