Skip to main content

Listener Library Reference

The listener library lets you build simple TCP‑based servers (for HTTP, custom protocols, etc.) entirely in EasyBite. You can:

  • Bind to a socket address
  • Listen for incoming connections, either a fixed number or until shutdown
  • Accept connections on demand
  • Serve forever, optionally invoking an EasyBite callback for each connection
  • Read raw request data and send formatted responses
  • Retrieve client info (addresses, raw socket handle)
  • Shutdown and join the server thread when you’re done

All you need is EasyBite’s listener module—no external scripting or manual thread management.

Importing​

import listener

// or pick specific functions
from listener import bind, listen, accept, response, readrequest, shutdown, clientinfo

Available Functions​

FunctionParametersDescription
bind(addr)addr (String)Bind a new server to the given address ("host:port") and store it globally.
listen([max_clients])max_clients (Number, optional)Start accepting connections in a background thread. Stops after max_clients or on shutdown.
start_server([server])server (HTTPListener, optional)Ensure one connection is accepted (blocks if none). Useful for simple single‑request servers.
serve_forever([server,] [callback])server (HTTPListener, optional), callback (Function, optional)Loop forever, accept each connection and—if callback given—invoke it in a new thread.
accept([server])server (HTTPListener, optional)Accept one connection (blocks if none queued).
join()—Wait for the server’s accept thread to finish (after shutdown or max clients).
response([conn,] message, [options])conn (TCPConnection, optional), message (String), options (Dictionary, optional)Send an HTTP‑style response. options may include "status" (e.g. "404 Not Found") and "headers".
readrequest([conn])conn (TCPConnection, optional)Read up to 1024 bytes from the connection and return as a String.
shutdown([server])server (HTTPListener, optional)Signal the background accept loop to stop.
clientinfo([conn])conn (TCPConnection, optional)Return a Dictionary with "peer_addr", "local_addr", and platform‑specific "raw_fd" or "raw_socket".

Examples​

1. Bind & Listen​

import listener

set server to listener.bind("0.0.0.0:8080")
set msg to listener.listen(3)
show(msg)
// Output:
// Listening on 0.0.0.0:8080
  • Binds to port 8080 and starts accepting up to 3 clients in a background thread.

2. Accept & Read One Request​

// Accept one connection (blocks until a client connects)
set conn to listener.accept()
// Read raw request data
set req to listener.readrequest(conn)
show(req)
// Output (example):
// "GET / HTTP/1.1\r\nHost: localhost:8080\r\n\r\n"

Note: You can also use listener.accept(conn) to accept a specific HTTPListener connection

3. Send an HTTP Response​

// Send a simple text response
listener.response(conn, "Hello, EasyBite!", {"headers":{"Content-Type":"text/plain"}})
// No return value; client receives:
// HTTP/1.1 200 OK
// Content-Length: 14
// Content-Type: text/plain
//
// Hello, EasyBite!

4. Serve Forever with Callback​

// Define a handler function
function handler(c)
    // Read the request
    set r to listener.readrequest(c)
    // Send back a greeting
    listener.response(c, "You said:\r\n" + r, {"status":"200 OK","headers":{"Content-Type":"text/plain"}})
end function

// Start accept loop, calling handler for each connection
listener.serve_forever(server, handler)

// ... elsewhere, to stop:
listener.shutdown(server)
listener.join()
  • serve_forever will block the current script until you call shutdown.
  • Each new connection runs handler in its own thread.

5. Fetch Client Info​

// After you accept a connection:
set info to listener.clientinfo(conn)
show(info["peer_addr"])
show(info["local_addr"])
show(info["raw_fd"])      // on Unix
// Output:
// "127.0.0.1:52344"
// "0.0.0.0:8080"
// 5
  • Provides low‑level details if you need to integrate with other systems.

Shutdown & Cleanup​

// Gracefully stop accepting
listener.shutdown(server)
// Wait for the background thread to exit
listener.join()

Conclusion​

With listener you can spin up TCP servers, handle raw requests, and send custom responses—all with EasyBite’s familiar syntax:

  • bind → open a port
  • listen → background accept loop
  • accept → manual accept
  • serve_forever → endless accept + callback
  • readrequest / response → your request/response logic
  • shutdown / join → clean exit

No manual socket API calls or thread boilerplate—just EasyBite code.