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.