CMLabs · Psyclone AIOS

# 11. Services & Interfaces

How the outside world talks to a Psyclone system: services process external requests, interfaces bind them to network ports and protocols.

## The model

Two elements cooperate to expose a Psyclone system on the network:

- A service is the thing that handles external requests — PsyProbe's web handler and the console are services.
- An interface is a network listener — a port with a protocol (`HTTP`, `Telnet`, `Message`, `RAW`; TCP by default, UDP with `ip="UDP"`) — that forwards connections to a service.

Several interfaces can share one port: the protocol is auto-detected from the first bytes of a connection, and if nothing is detected within the timeout, the `default="yes"` interface is assumed.

## Built-in services

Unless disabled, every system implicitly gets PsyProbe and the console, as if the spec contained:

    <service name="PsyProbe" root="../html" />
    <service name="Console" />
    <interface name="PsyProbe" protocol="HTTP"   service="PsyProbe" />
    <interface name="Console"  protocol="Telnet" service="Console" />

Disable either by pointing the protocol at no service:

    <interface protocol="HTTP"   service="none" />
    <interface protocol="Telnet" service="none" />

## Custom services

A custom service is declared like a small module: its triggers/posts bridge external requests into the pub/sub bus, and an interface binds it to a port. A web service:

    <service name="MyWebService">
      <trigger type="Data.Web.Reply" from="wb" />
      <post type="Data.Web" to="wb" />
    </service>
    <interface name="MyWebInterface" port="6789" protocol="HTTP" service="MyWebService" />

An incoming HTTP request becomes a `Data.Web` message; whichever component posts the matching `Data.Web.Reply` supplies the response. The same pattern works with `protocol="Telnet"` for line-based consoles, and with `protocol="Message"` for full DataMessage exchange with a remote CMSDK-linked program (a trigger-only variant keeps the incoming message types; adding a post rewrites types before posting).

Warning. Stub In the current build, custom services are registered and their component is created, but they are wired with a NULL receiver — inbound requests to custom web/telnet/message services are discarded. The built-in PsyProbe and Console services work normally. Track this before designing around custom services.

## Protocol auto-detection on a shared port

Multiple interfaces can listen on the same port; each connection is sniffed and routed:

    <interface name="MyWebInterface" node="Node0" port="1234" protocol="HTTP"
               service="MyWebService" timeout="3000" default="yes" />
    <interface name="MyTelnet"  port="1234" protocol="Telnet"  service="MyTelnetService" />
    <interface name="MyMsgLink" port="1234" protocol="Message" service="MyMsgService" />

After 3 seconds with no recognisable protocol, the default (here HTTP) interface takes the connection. Interface attributes: `name` (required), `service` (required), `port` (required), `node`, `protocol`, `timeout`, `default`, plus the SSL verification attributes `allowselfsigned` / `cafile` / `capath` (see the reference).

## How clients connect

- Browsers — hit the main port (default 10000) or a dedicated PsyProbe/HTTP interface: `http://hostname:10000/`.
- Terminals — telnet to a Telnet interface for the console service.
- Programs — link CMSDK and connect to a `Message` interface to exchange DataMessages, or run as an external-space component for full module semantics.

Note. Administration-level detail — Telnet console usage, running PsyProbe on custom ports, securing interfaces with SSL certificates, and the `<authentication>` element (currently a parse-only stub) — lives in the System Guide.
PreviousDistributed Systems NextPsyProbe