Skip to content
SHC Docs

Your own socket and plug

This page writes both ends of an integration: a socket and a plug. The app ladder’s A Postgres socket plugs an app into a socket the catalogue ships. A socket is what a provider offers: the data a consumer reads, and jobs that provision something for each consumer. A plug is what a consumer asks for. Connecting one to the other is an integration, and its jobs run in phases: discovery and integration on the provider, post_deployment on the consumer, and unintegration on both when the edge goes.

guestbook’s counter becomes a socket. Each consumer gets a key of its own in it, set to zero when it connects and deleted when it leaves. Add the socket file to guestbook on home01.

~/learn/guestbook/counter.socket.yaml
service: counter
placement:
colocate: location
schema:
plug:
key@string!: the key the consumer counts in
socket:
hostname@string!: the counter's address
port@port!: its port
data:
hostname: "{{ environment }}.counter.{{ stack }}"
port: 6379
jobs:
discovery:
- name: ping
context: service
service: counter
command: redis-cli ping
integration:
- name: start-key
context: service
service: counter
command: redis-cli setnx {{ integration.plug.data.key }} 0
unintegration:
- name: drop-key
context: service
service: counter
command: redis-cli del {{ integration.plug.data.key }}
  • service names the service the socket fronts, the one its address reaches.
  • placement.colocate: location places a consumer in the counter’s location, since it dials the counter on every request.
  • schema types both sides of the edge: what a plug must send, and what the socket hands back.
  • data is what a consumer reads, rendered for each integration. Its hostname is the counter’s name on guestbook’s network.
  • Each job sees the edge as integration.plug.data and integration.socket.data. ping proves the counter answers before anything is provisioned.
home01
$ shc update guestbook
...
$ shc integration
...
$ shc integration sockets
...
$ shc integration sockets --all
...

Now the consumer. tally is a Redis client that counts in its own key.

~/learn/tally/app.yaml
name: tally
version: "1.0.0"
title: Tally
description: Counts in a key of guestbook's counter
category: demo
license:
id: MIT
~/learn/tally/counter.plug.yaml
socket: counter
required: true
services:
- tally
schema:
plug:
key@string!: the key tally counts in
data:
key: tally
jobs:
post_deployment:
- name: first-count
context: service
service: tally
command: redis-cli -h {{ integration.socket.data.hostname }} incr {{ integration.plug.data.key }}
unintegration:
- name: last-count
context: service
service: tally
command: redis-cli -h {{ integration.socket.data.hostname }} get {{ integration.plug.data.key }}
~/learn/tally/shc.yaml
services:
tally:
image: redis:7-alpine
entrypoint: ["sh", "-c"]
command: ["sleep infinity"]
environment:
COUNTER_HOST: "{{ integrations.counter.socket.hostname }}"
COUNTER_KEY: "{{ integrations.counter.plug.data.key }}"

The plug’s file name is its name, counter; socket says which socket it wants, here the same word. required: true refuses an install that does not connect it. services attaches only tally to guestbook’s network. After the jobs run, the edge’s data is in the render as integrations.counter, which shc.yaml passes to tally as two variables.

home01
$ shc install ~/learn/tally -s tally
installing deployment "tally"
shc: [X400994PLGREQ] app /root/learn/tally required plugs not connected, counter, connect each with -i plug=provider or point its vars at an external service via --var
$ shc install ~/learn/tally -s tally -i counter=guestbook
...
$ shc integration ls
...
$ shc integration ls --all
...
$ shc integration plugs
...
$ shc integration plugs --all
...

start-key set tally to zero on the counter, and first-count added one once tally ran. tally reads the counter’s address and its key from its environment.

home01
$ shc exec -s guestbook -S counter -- redis-cli get tally
1
$ shc exec -s tally -S tally -- sh -c 'redis-cli -h "$COUNTER_HOST" incr "$COUNTER_KEY"'
2

A required plug cannot be dropped from a running deployment, so tally keeps its edge until it goes. Uninstall runs the edge’s unintegration jobs, the consumer’s first and then the provider’s, so tally reads its count before the counter deletes the key.

home01
$ shc update tally -i counter!
updating deployment "tally"
X200972RMVDON: -i removal counter matched this deployment and was applied to its persisted state
shc: [X400994PLGREQ] app /root/learn/tally required plugs not connected, counter, connect each with -i plug=provider or point its vars at an external service via --var
$ shc uninstall tally --yes
...
$ shc exec -s guestbook -S counter -- redis-cli exists tally
0

A socket that fronts an outside service hands each consumer the service’s own key: credentials lists the data fields stamped over the plug’s fields of the same name. guestbook’s counter has no key to hand out, so write the shape on an app that is validated and never installed.

~/learn/keyfront/app.yaml
name: keyfront
version: "1.0.0"
title: Keyfront
description: Fronts an outside store and hands each consumer its key
category: demo
license:
id: MIT
vars:
endpoint@url: the outside store's address
accessKey@string: the store's access key
secretKey@secret: the store's secret key
~/learn/keyfront/vars.yaml
endpoint: https://store.learn.test
accessKey: learn-access
secretKey: "ref+vault://store_secret?autogen"
~/learn/keyfront/store.socket.yaml
service: front
credentials:
- accessKey
- secretKey
schema:
socket:
endpoint@string!: the store's address
accessKey@string!: the key a consumer signs with
secretKey@string!: its secret
data:
endpoint: "{{ vars.endpoint }}"
accessKey: "{{ vars.accessKey }}"
secretKey: "{{ vars.secretKey }}"
~/learn/keyfront/shc.yaml
services:
front:
image: nginx:1.27-alpine
expose: [80]
home01
$ shc validate ~/learn/keyfront
...

update --connection rebinds a connection an app declares in app.yaml, name=connection, to another of the admin’s connections. Nothing on this ladder declares one.

explained, not walked: no app of this ladder declares a connection
$ shc update tally --connection llm=openai-team

Next: Add-ons.