Unix sockets transport

This transport lets a process on the same machine talk to Janus through a socket file, with no network port. Use it for a local supervisor, a sidecar, or a test script. Access control is the file permission on the socket path. As on WebSockets, one socket carries both requests and the events of its sessions.

The transport has two socket types:

• SOCK_SEQPACKET (the default): the client connects, and replies and events come back on that connection. Closing the connection ends its sessions.
• SOCK_DGRAM: no connection. The client binds its own socket path and sends datagrams to Janus's path. Janus replies to the path the datagram came from.

Both carry one JSON message per packet. From the source (not tried here): 8191 bytes at most, and a longer packet is dropped.

macOS has no SOCK_SEQPACKET

SOCK_SEQPACKET does not exist for Unix sockets on macOS. With the default type, Janus on macOS logs a fatal error for the socket and the transport does not start (transcript below). Set type = "SOCK_DGRAM" there. Linux supports both. I ran this page's examples on macOS with SOCK_DGRAM: the SOCK_SEQPACKET path was not run here (the status file says it was checked on Linux).

Enable and configure

The transport reads janus.transport.pfunix.jcfg. It is off unless general.enabled (Janus API) or admin.admin_enabled (Admin API) is true.

general: {
	enabled = true
	json = "indented"                 # indented, plain or compact (the default)
	path = "/var/run/janus/api.sock"  # where to bind (Janus API)
	type = "SOCK_DGRAM"               # or SOCK_SEQPACKET, the default
}
admin: {
	admin_enabled = true
	admin_path = "/var/run/janus/admin.sock"
	admin_type = "SOCK_DGRAM"
}

As in the C server, Janus deletes an old file at path before it binds and deletes the socket at shutdown. The user that runs Janus needs write access to the folder; clients need write access to the socket (for SOCK_DGRAM, to send to it). A socket path is limited to about 100 bytes on macOS and Linux. The full key table is in the transport files reference.

Try it

The client is python3 with the socket module (any language that has Unix sockets works). It binds client.sock, sends datagrams to Janus's socket, and prints what comes back. The transcript is the output of that script. The last two requests go to the Admin socket.

// Config: general.path and admin.admin_path, type SOCK_DGRAM. A datagram client binds its own socket path, which the server replies to.

// → send
{
  "janus": "ping",
  "transaction": "u1"
}

// ← receive
{
  "janus": "pong",
  "transaction": "u1"
}

// → send
{
  "janus": "create",
  "transaction": "u2"
}

// ← receive
{
  "janus": "success",
  "transaction": "u2",
  "data": {
    "id": 7586225842247060
  }
}

// → send
{
  "janus": "attach",
  "session_id": 7586225842247060,
  "plugin": "janus.plugin.echotest",
  "transaction": "u3"
}

// ← receive
{
  "janus": "success",
  "session_id": 7586225842247060,
  "transaction": "u3",
  "data": {
    "id": 277723047735280
  }
}

// → send
{
  "janus": "message",
  "session_id": 7586225842247060,
  "handle_id": 277723047735280,
  "transaction": "u4",
  "body": {
    "audio": true
  }
}

// ← receive
{
  "janus": "ack",
  "session_id": 7586225842247060,
  "transaction": "u4",
  "hint": "I'm taking my time!"
}

// ⇠ receive (pushed, no request)
{
  "janus": "event",
  "session_id": 7586225842247060,
  "transaction": "u4",
  "sender": 277723047735280,
  "plugindata": {
    "plugin": "janus.plugin.echotest",
    "data": {
      "echotest": "event",
      "result": "ok"
    }
  }
}

// admin socket

// → send
{
  "janus": "list_sessions",
  "transaction": "u5",
  "admin_secret": "janusoverlord"
}

// ← receive
{
  "janus": "success",
  "transaction": "u5",
  "sessions": [
    7586225842247060
  ]
}

// the same request without the secret

// → send
{
  "janus": "list_sessions",
  "transaction": "u6"
}

// ← receive
{
  "janus": "error",
  "transaction": "u6",
  "error": {
    "code": 403,
    "reason": "Unauthorized request (wrong or missing secret/token)"
  }
}

This is what the default type does on macOS:

// ⇠ janus log with type left at its default (SOCK_SEQPACKET), on macOS
Configuring SOCK_SEQPACKET Unix Sockets server (Janus API)
JANUS Unix Sockets transport plugin initialized!
JANUS Unix Sockets transport plugin initialized!
[FATAL] Unix Sockets /tmp/ux-janusapi creation failed: 43, Protocol not supported
janus: the Unix sockets transport did not start: Protocol not supported (os error 43)

Reference

Writing a client

	SOCK_DGRAM	SOCK_SEQPACKET
Open	socket(AF_UNIX, SOCK_DGRAM), bind() your own path	socket(AF_UNIX, SOCK_SEQPACKET), connect() to Janus's path
Send	sendto(json, janus_path)	send(json)
Receive	recv() on your bound socket: replies and events both	recv(): replies and events both
Session ends when	the session is destroyed or times out	the connection closes (unless reclaim_session_timeout keeps it), or it is destroyed

A SOCK_DGRAM client must bind a path. An unbound client socket gives Janus nowhere to send the reply.

Requests are the same JSON as on every transport, with session_id and handle_id in the body. Replies and events are the same JSON, in the format chosen by json.

The Admin API

The Admin socket takes Admin requests only, with admin_secret. The transcript shows the same list_sessions with and without the secret: without it, error 403.

Behaviour you may not expect

• verified Events are pushed to the client that created the session. In the transcript the event for the echotest message arrived on the same socket after the ack.
• verified Janus writes its log line Configuring SOCK_DGRAM Unix Sockets server (Janus API) per socket at start. Look for it to know which type it took.
• A type that is neither value is read as SOCK_SEQPACKET, with a warning (from the C source).
• verified A SOCK_DGRAM client is a "connection" for event handlers: its first datagram makes Janus send a transport event connected with "fd": -1 and "type": "SOCK_DGRAM". C does the same.
• Janus reads the sender path of a datagram as a C string, so a client path with embedded NUL bytes is cut there.

Known gaps

• gap On macOS the default type fails (see above). The C server fails the same way. The transcript shows Janus still lists the transport in its log line JANUS Unix Sockets transport plugin initialized! before the failure, and info still lists janus.transport.pfunix although the socket is not there.
• gap SOCK_SEQPACKET was not run here. The parity/status.json note for this component says it was checked on Linux with a real client.
• gap session created events for sessions made on this transport do not carry the transport object that C adds.
• gap query_transport answers error 490.

Test it in Janus Bench

Janus Bench talks HTTP and WebSockets only. There is no check for this transport. The parity crate has the Unix socket cases of the differential harness.