CMLabs · Psyclone AIOS

# 4. Custom Interfaces

Services and interfaces: the built-in PsyProbe and Console endpoints, custom HTTP/Telnet/Message ports, protocol autodetection — and what is honestly stubbed.

## Services vs interfaces

Psyclone separates what is served (a service) from where and how it is reachable (an interface). Two of each are created automatically unless disabled — the implicit defaults are equivalent to:

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

To disable a built-in endpoint (a common hardening step — see Security & SSL):

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

## The Telnet console

The built-in Console service listens on the main port via protocol autodetect: `telnet host 10000` gives an interactive text console into the running system. Because it shares the main port, no extra firewall hole is needed — but conversely, anyone who can reach the main port can reach the console. Disable it (above) or bind it behind an SSL/firewalled port in production.

## <interface> reference

    <interface name="MyWebInterface" node="Node0" port="1234"
               protocol="HTTP" service="MyWebService"
               timeout="3000" default="yes" />

Attribute | Meaning | Default
--- | --- | ---
`name` | Interface name (required; parse fails without) | —
`service` | Target service name (required) | —
`port` | TCP/UDP port (required) | —
`protocol` | `Message` | `HTTP` | `Telnet` | `RAW` (anything else = parse failure) | —
`node` | Node the interface listens on | local
`timeout` | Autodetect timeout, ms | unset
`default` | `yes` = assumed protocol when autodetect times out | no
`ip` | `UDP` selects UDP; otherwise TCP | TCP
`allowselfsigned`, `cafile`, `capath` | Per-interface SSL verification overrides — see Security & SSL Shipped | inherit global

## Custom services

A custom service is a component with triggers and posts, wired to an interface on its own port. A web service that hands requests to a whiteboard and returns replies:

    <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" />

The Telnet analogue uses `protocol="Telnet"`. A Messaging service (`protocol="Message"`) lets a remote program linking CMSDK exchange DataMessages directly; declared with only a trigger it accepts the types already in the incoming messages, while adding a post rewrites the type before delivery.

Warning. Stub In the current code base, custom web/telnet/message services are registered with a NULL receiver — inbound requests on custom services are discarded. The built-in PsyProbe and Console services work; treat custom services as parsed-but-stubbed until this is completed. Plan custom HTTP needs around PsyProbe subsites and the RequestStore API (chapter 3) in the meantime.

## Protocol autodetection: several protocols on one port

Multiple interfaces may share one port; Psyclone sniffs the first bytes to pick the protocol, and after `timeout` ms with nothing conclusive it assumes the interface marked `default="yes"`:

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

This is exactly how the main port serves PsyProbe (HTTP), the Console (Telnet) and node-to-node Message traffic simultaneously.

## Authentication and encryption attributes Stub

The spec format reserves an `<authentication>` child on interfaces, and interface-level encryption attributes (SSL/AES256) appear in the newer spec documentation. Both are currently parsed but not acted on: the authentication parser body is empty and returns success, and the encryption attributes have no wiring. Do not rely on them for security. What is shipped is SSL transport with certificate verification for connections — the subject of the next chapter.

PreviousPsyProbe Configuration NextSecurity & SSL