Services#
A System has a set of Services. A Service provides a capability used by Process code: HTTP, TCP, database, storage, cache, SMTP, messaging or SecretsProvider operations.
A Service has a name, a description, a type and its configuration. Its description explains the capability it provides and its purpose in the System. Different connections or configurations can be declared as separate Services of the same type.
The produced file is services/<service-name>.json; it follows Service.schema.json. It declares the capability and configuration, not the code that invokes it. languages/aiscript/AIScript.md defines those calls.
| Property | Meaning |
|---|---|
name |
Service name, unique among Services in this System and used in calls, references and its filename. |
description |
Purpose of the capability. |
type |
http, tcp, database, storage, cache, smtp, mom (messaging) or secrets. |
audiences |
Exact Audience names, or omitted/empty for shared availability. |
spec |
Service configuration, including publication-time expressions for declared Secrets. Never confidential values. |
secrets |
Optional dependency metadata listing declared Secret names. This list does not inject values; expressions in spec identify their destination. |
protocols, exchanges |
TCP message definitions and request/response protocol selection. |
Supported Types#
| Type | Meaning |
|---|---|
http |
Send requests to an HTTP service and handle its responses. |
tcp |
Exchange encoded messages with a TCP server using declared protocols. |
database |
Create, query and update Data Collection records. |
storage |
Work with filesystem objects: files and folders under the configured root. |
cache |
Store and retrieve reusable values by key, locally in JVM memory or in a shared store. |
smtp |
Send email through a mail server. |
mom |
Publish and receive messages; Events describe their business payloads. |
secrets |
Use the runtime's default SecretsProvider operations through a declared Service. |
The sections below explain each type. languages/aiscript/AIScript.md documents the calls.
Configuration By Service#
Declare each Service with its name, description, type and spec. The author chooses the names.
| Service | What the author configures |
|---|---|
| Database | spec: { "type": "database.rdb.postgres" }. Collections define the data. The runtime supplies the database connection and pool. |
| Shared cache | spec: { "type": "cache.redis.native" }. The runtime supplies the cache nodes and connection. |
| Messaging | spec: {}. Events define messages and their association with Processes. The runtime supplies the messaging bus and its protected connection configuration. |
| Shared storage | spec: { "type": "storage.fs.native" }. The runtime supplies the shared root folder. Process code chooses paths inside it. |
| Local memory cache | spec: { "type": "cache.caffeine.native" }, optionally with capacity and expiry settings shown below. |
| Secrets | spec: { "type": "secrets.native" }. Uses the default provider; no connection settings are authored. |
| HTTP | The partner address and request settings: method, path, headers and supported transport options. Declare confidential values as Secrets. |
| TCP | The partner host, port, timeouts, pool settings, protocols and exchanges shown below. Declare confidential values and required TLS material as Secrets. |
| SMTP | The mail server host and optional sending thread-pool size. Declare the sending account and credential as Secrets. The native configuration uses authenticated STARTTLS on port 587. |
Publication supplies the runtime-provided connection configuration. Confidential Service configuration is stored through the default SecretsProvider; the installed Service spec contains only { "secret": "<provider-token>" }. The author declares the Service and its requirements, not the token or the runtime hosts, ports and credentials.
Architecture-bound Services use the configuration of the selected Runtime. Provisioning creates and protects that configuration; publication binds the authored Service to it. Infrastructure credentials are not additional business Secret declarations for the author to invent.
Audience Availability#
A Service can be shared by all Audiences or assigned to specific Audiences. An omitted or empty audiences list means it is shared. Otherwise, the list identifies the Audiences whose Processes use it. This association describes Service availability, not an access policy.
Processes declare the Services they use as dependencies and call them through the interfaces defined in languages/aiscript/AIScript.md.
Names#
The author chooses the meaningful part of a Service name. Put the capability first: http_partner, tcp_partner, database_default, storage_default, cache_local_default, cache_shared_default, smtp_default, mom_default and secrets_default. For example, use http_partner, not partner_http. These are naming conventions, not implementation selectors; the Service's type and configuration define its behavior.
Use the chosen name exactly in its filename, Process dependencies and Service lookups. Names such as database_default in the code examples are examples, not reserved or required names. A naming convention does not make an unimplemented Service available.
HTTP#
An HTTP Service makes outbound HTTP requests. Its configuration describes the remote address and request settings, such as the method, path, headers and timeout. Process code supplies the request values and body and handles the returned status and content.
An HTTP Service is not an incoming endpoint. Incoming business actions are Processes.
The configuration has a fixed structure:
| Property | Meaning |
|---|---|
spec.type |
net.http.native. |
spec.version |
Optional HTTP_1_1 (default) or HTTP_2. |
spec.connectTimeout |
Optional connection timeout in milliseconds; default 30000. |
spec.ssl |
Optional key, certificate and trustCAs identifiers supplied from declared Secrets through the default SecretsProvider. |
spec.request.verb |
Lowercase get, post, put, delete, patch or head; default post. |
spec.request.path |
Full destination URL, including any query string. |
spec.request.headers |
Header names and values. Values are converted to text. |
spec.request.timeout |
Optional positive request timeout in milliseconds; default 30000. |
spec.request.async |
Optional boolean; default false. True submits asynchronously and discards the response. |
Use these exact property names: verb, not method. There is no separate HTTP server.host. The request has no body property; AIScript code uses send(body, overrides) with optional per-call overrides second. For example, partner.send({ reference: input.reference }) uses the declared request settings without a placeholder argument. AIScript converts data to bytes using its documented rules; strings use UTF-8 and existing bytes pass unchanged. Only post, put and patch send those bytes; get, delete and head do not.
spec.request is required and can be empty when code supplies its settings through send overrides. The effective request must have a full HTTP or HTTPS URL in path before sending. Overrides use the same request properties and apply to that call only. Secret expressions are resolved at publication, not by the HTTP call.
Some interactions return a URL for a person to open, require a browser return URL, or deliver their result later to a callback Process. These are ordinary Service interaction requirements, not a new Service type. Process.md explains the corresponding Process contracts.
A synchronous request returns the remote response to the caller. A fire-and-forget request starts the request asynchronously and does not return the remote result. Submission alone does not establish that the remote business action succeeded.
TCP#
A TCP Service exchanges messages with a remote server. Its configuration describes the connection and the protocols used to construct and read messages.
A protocol defines message structure and framing: how fields are encoded and how a complete message is identified in the byte stream. The Service's protocols and exchanges identify the request and response formats. Process code constructs a message according to the declared protocol rather than assuming that one network read equals one message.
An exchange can wait for its response or run asynchronously. In the asynchronous form, the complete exchange still runs and its response is consumed, but that response is not returned to the calling Process. This is not a one-way protocol or a durable queue.
Database#
A database Service gives Processes access to Data Collection records. Processes use it to create records, retrieve and query records, and update records, including soft deletion.
For an individual record, use first to load it, change its fields and call save. When processing records individually from a query, change and save each Record. Use update for bulk changes to matching records, not as the single-record editing pattern. AIScript describes the calls and locking rules.
To clear an optional field value, call record.remove(name) and save the Record. This does not delete the record or change its Collection definition.
The Collections define the stored fields and relationships. The Process defines the business operation performed on those records. Database calls use these declared fields and relationships, not a separate informal representation of the data.
Storage#
A storage Service gives Processes access to files and folders. It can be used to retrieve a file, inspect it or store a generated document. File contents and the Collection record describing a file are different things: the storage holds the contents, while a File field holds the information needed to identify and present the file.
Systems on the same Runtime use the configured shared storage root. The upload folder is reserved for uploads in progress and cdn for finalized media. A System can use other folders under that root for its own files. Folder selection does not replace access checks on file retrieval.
Caches#
A cache holds values by key so they can be reused without repeating the work that produced them. A cached value can expire or be invalidated. Its key identifies the value; its expiry describes how long it can be reused.
A Local Memory Cache holds values in JVM memory. Copies running in other JVMs have independent contents, even when those JVMs run on the same machine. Each configured Service owns its entries. Capacity and write/idle expiry are configured on the Service; calls may also supply a per-entry TTL. Process code obtains the cache through the declared Service name.
A Shared Cache holds values in a store accessible to multiple JVMs or machines. Calls using the same store and key can access the same cached value. Process code uses the declared cache Service.
The author decides which cache behavior the System needs, what the keys represent and how cached values are refreshed or invalidated.
Secrets Service#
A Secrets Service exposes the default SecretsProvider interface. Its type is secrets and its non-sensitive configuration is { "type": "secrets.native" }. It requires no provider selection or credentials in the System Design. Inside a function, Process code acquires it with secrets = service "secrets_default" and calls methods on that value, such as secrets.tokenize(bytes, ttlSeconds). There is no global SecretsProvider object in AIScript. The name must match the declared Service and Process dependency. languages/aiscript/AIScript.md describes its operations and types. Secret resources still declare the material needed by those operations; a Service declaration is not a confidential value.
SMTP#
An SMTP Service sends email. Its configuration describes the mail server and connection settings. A Process supplies the recipients, subject and content, including any template data used to construct the message.
Email content belongs to the business action: it should explain the outcome and any next step accurately. Credentials belong in Secrets, not in templates or message content. Queuing a message for sending is different from confirming delivery to its recipient.
For example, this Service requires a declared object Secret named mailAccount, whose properties are user and password:
{
"name": "smtp_default",
"description": "Send notifications using the account declared in mailAccount; its user and password supply SMTP authentication.",
"type": "smtp",
"spec": {
"type": "notification.mail.native",
"server": {
"host": "smtp.example.com"
},
"auth": {
"user": "{{ security.secrets.mailAccount.user }}",
"password": "{{ security.secrets.mailAccount.password }}"
},
"threadPool": {
"size": 5
}
},
"secrets": [
"mailAccount"
]
}
Messaging#
A messaging Service publishes messages on subjects. Events describe the business information carried by those messages. Processes emit Events or receive their values through the declared Event-to-Input mappings.
When a Process is associated with an incoming Event, the generator creates its subscription and listener. The author writes the Process behavior, not listener code. Publishing from Process code uses the methods in languages/aiscript/AIScript.md.
The Service supplies transport; the Event supplies the meaning and payload. A messaging Service is not an Audience.
Configuration And Secrets#
A Service's spec shows where each declared Secret is used. Use {{ security.secrets.<name> }} for a whole Secret and append a property path for an object Secret. The prefix is always security.secrets..
{
"name": "http_provider",
"description": "Send partner requests. Authorization requires the declared providerAuthorization Secret.",
"type": "http",
"secrets": [
"providerAuthorization"
],
"spec": {
"type": "net.http.native",
"request": {
"verb": "post",
"path": "https://partner.example/orders",
"headers": {
"Content-Type": "application/json",
"Authorization": "{{ security.secrets.providerAuthorization }}"
}
}
}
}
The security team supplies approved material. Publication resolves these expressions before deployment. A stored-value expression supplies its value; an object expression can supply the complete object or one of its properties; a key or certificate expression supplies its approved provider identifier. For example, {{ security.secrets.partnerConnection.clientSecret }} selects one declared property. An expression occupying the whole value preserves its type; text such as Bearer {{ security.secrets.partnerToken }} builds a string.
Publication supplies approved values for these expressions. The author includes only references, never actual credentials. A missing required Secret or object property must not silently become an empty credential. Runtime provisioning, protection of installed configuration and assignment of actual values are handled outside the System Design.
The installed protected configuration uses a provider token:
{
"secret": "<provider-token>"
}
The token identifies bytes containing the complete Service configuration as a JSON object. It is not an external access token, a plaintext credential or a reference to one property. The security/publication workflow supplies this installed configuration. The authored Service still declares its non-sensitive configuration and named Secret requirements; the author does not manufacture a token or include real token values in the System files.
When Process code needs a confidential value directly, its provider lookup comes only from security.secrets.<name>.path and security.secrets.<name>.key. Provider operation identifiers come from security.secrets.<name>. Names must correspond to declared Secrets. Secret.md and languages/aiscript/AIScript.md explain the interfaces.
A calculated signature uses the provider's sign operation with an injected key identifier. An external access token requires the partner's authentication exchange. Neither is an automatically substituted static value.
Actual values are not included in the authored System. Publication supplies the installed configuration and application properties needed by each API according to its Audience and dependencies. These are publication responsibilities, not additional cryptographic code for the author to implement.
The Service specification is Service.schema.json. Service calling interfaces are defined in languages/aiscript/AIScript.md. Connection configuration and deployment wiring are outside Process code.
TCP Protocol Definition#
A TCP Service declares named protocol definitions in protocols. An exchange selects a requestProtocol and responseProtocol by those names. The definition is the existing native protocol format, not a second language to translate. The protocol resource defines the message structure; Process code supplies its values.
The definition supports fixed and length-prefixed fields, primary and secondary bitmaps, nested composite fields and TLV data. These building blocks can describe ISO-8583 and other structured protocols. The peer's protocol determines the fields and encodings to declare. The sections below explain this definition format and its supported behavior.
| Property | Meaning |
|---|---|
name, description |
Protocol name and explanation. |
frame |
Length prefix for the complete message payload. |
sections |
Object of named sections, serialized in declaration order. |
Section fields |
Array of fields serialized in declaration order when there is no bitmap. |
Section bitmap |
Optional bitmap selecting fields by numeric id. |
Field name, id |
Name used in message values, and numeric identifier used by a bitmap. |
Field type, endian |
Value encoding and byte order. |
Field length |
Fixed width, a field-length prefix, or the remaining payload. |
Field fields, bitmap |
Nested section for a composite field. |
Field tlv |
Declared tag/length/value entries within the field. |
Frames And Field Lengths#
The serializer prepends the payload byte count; the count excludes the frame prefix itself. frame.length is the prefix width in bytes. frame.type is uint or binary for a binary count, or ascii or numeric for decimal ASCII digits. The property is type, not format. The examples below use endian: "big".
Although the parser accepts endian: "little", the current integer framing implementation still writes the length in big-endian order. Do not assume little-endian framing works merely because the property is accepted. A peer requiring it needs a separately reviewed capability or correction; this document does not introduce a generator workaround.
Field lengths are different from the message frame:
{"format":"fixed","value":8}occupies eight bytes. Simple fields can be truncated or padded; validate business lengths before sending.{"format":"prefixed","value":2}prepends two decimal ASCII digits containing the field's byte length. Three digits usevalue: 3. The ordinary field serializer does not uselength.typeto select a binary length prefix.{"format":"remaining"}consumes the rest of the payload on decoding. Use it only where that meaning is correct, such as the final top-level field; it does not mean the rest of an arbitrary nested section.
variable exists in the length enumeration but is not an ordinary field-length implementation. It must not be used as a substitute for a supported length format. Prefix capacity and field value constraints must match the peer's protocol.
Value Types#
ascii and numeric use ASCII bytes and decode to strings. numeric preserves digit text; it is not a business integer conversion. bcd uses packed decimal digits. uint represents an unsigned integer. binary accepts bytes or hexadecimal text when encoding and decodes to bytes. msb and lsb represent Java BitSet values. emv is a structural TLV length encoding, not a normal scalar field type.
Request And Response Example#
This TCP Service includes its connection settings and a request/response exchange. The request has a body.reference value with a two-digit ASCII length. The response has a two-byte body.status value. The names select the protocols used by the companion TCP code examples. Replace the example address with the peer's address.
{
"name": "tcp_provider",
"description": "Exchange reference and status messages with a partner.",
"type": "tcp",
"spec": {
"type": "net.tcp.native",
"server": {
"host": "partner.example",
"port": 9000
},
"connectTimeout": 30000,
"readTimeout": 5000,
"pool": {
"size": 2,
"waitTime": 1000
}
},
"exchanges": [
{
"name": "reference-status",
"requestProtocol": "request-message",
"responseProtocol": "response-message",
"async": false
}
],
"protocols": [
{
"name": "request-message",
"definition": {
"name": "Request Message",
"frame": {
"length": 2,
"type": "uint",
"endian": "big"
},
"sections": {
"body": {
"fields": [
{
"id": 1,
"name": "reference",
"type": "ascii",
"length": {
"format": "prefixed",
"value": 2
}
}
]
}
}
}
},
{
"name": "response-message",
"definition": {
"name": "Response Message",
"frame": {
"length": 2,
"type": "uint",
"endian": "big"
},
"sections": {
"body": {
"fields": [
{
"id": 1,
"name": "status",
"type": "ascii",
"length": {
"format": "fixed",
"value": 2
}
}
]
}
}
}
}
]
}
A request with reference equal to ABC produces hexadecimal bytes 00 05 30 33 41 42 43: a five-byte payload consisting of 03 followed by ABC. A response with status equal to OK produces 00 02 4F 4B.
| Connection property | Meaning |
|---|---|
server.host, server.port |
Peer address and TCP port. |
connectTimeout |
Connection timeout in milliseconds; defaults to 30000. |
readTimeout |
Response read timeout in milliseconds; defaults to 5000. |
pool.size |
Number of pooled connections; defaults to 10. |
pool.waitTime |
Maximum wait for a pooled connection in milliseconds. Supply a positive value. |
ssl.key, ssl.certificate, ssl.trustCAs |
Installed TLS key, certificate and trust identifiers when TLS is needed. Declare their requirements as Secrets; publication supplies the installed configuration. |
Process code selects the protocols through RequestProtocol and ResponseProtocol lookup parameters, as shown in languages/aiscript/examples/tcp-cache.ais. A protocol definition describes the bytes; the connection settings describe where they are sent.
Bitmaps And Composite Fields#
A section bitmap defines primary, secondary, type and bitOrder. Lengths are wire byte counts. For example, an eight-byte binary primary bitmap can represent 64 bits; an ASCII hexadecimal representation requires 16 wire bytes for those bits. The current bitmap path supports primary and secondary maps through field 128. Bit 1 indicates the secondary map, not a normal business field.
A composite field declares its own fields array and optional bitmap, using its outer length to delimit the encoded content. Message values for that field are a nested object. Field identifiers must match the peer's bitmap positions; declaration order alone is not sufficient for bitmap sections.
TLV Entries#
A TLV field declares an ordered tlv array. Each entry defines name, tag, length and value. tag describes its bytes and width; length describes the length of the entry's value; value.type describes the value encoding. length.type: "emv" selects BER/EMV definite-length encoding for the entry length.
For a fixed tag such as hexadecimal 9F02, use that hexadecimal value as the entry name and its tag.name, with tag.type: "binary" and tag.length: {"format":"fixed","value":2}. An entry value can use value: {"type":"binary"} and length: {"type":"emv"}. Process code supplies named values inside the TLV field's object.
The current decoder walks the declared tag entries in order and checks their tag values. It is not a general decoder for arbitrary tag order, unknown tags or any partner's full payment protocol. Declare and test the agreed map. Likewise, a TCP framing definition does not by itself implement the business meaning of a payment message.
Shared Cache Configuration#
{
"name": "cache_shared_default",
"description": "Reusable values shared by the System's JVMs.",
"type": "cache",
"spec": {
"type": "cache.redis.native"
}
}
The runtime supplies the shared-cache nodes and credentials. Publication installs the protected configuration; the author does not specify those addresses in this declaration.
languages/aiscript/AIScript.md explains the calls; languages/aiscript/examples/cache-shared.ais stores and reads a value using the supplied lifetime and a System-qualified key. A zero or negative TTL uses an ordinary write without expiry in this shared-cache interface.
Local Memory Cache Configuration#
{
"name": "cache_local_default",
"description": "Reusable local values held independently in each JVM.",
"type": "cache",
"spec": {
"type": "cache.caffeine.native",
"maxSize": 10000,
"expireAfterWrite": 300,
"expireAfterAccess": 60
}
}
Expiry values are seconds. Each zero disables that configured limit. The earlier expiry applies; access can refresh the idle limit, not a write or per-entry deadline. Capacity is an entry count. With no explicit settings, capacity is 10,000 entries and there is no time-based expiry. Closing a request does not clear the Service's entries; unloading the Service does.
Secrets Service Configuration#
{
"name": "secrets_default",
"description": "Access the runtime-provided confidential values and cryptographic operations.",
"type": "secrets",
"spec": {
"type": "secrets.native"
}
}
The name is author-chosen. Process code uses this exact name in Service lookup and dependencies. This Service always uses the default SecretsProvider; it does not create or manage another provider.