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.
service: counterplacement: colocate: locationschema: plug: key@string!: the key the consumer counts in socket: hostname@string!: the counter's address port@port!: its portdata: hostname: "{{ environment }}.counter.{{ stack }}" port: 6379jobs: 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 }}servicenames the service the socket fronts, the one its address reaches.placement.colocate: locationplaces a consumer in the counter’s location, since it dials the counter on every request.schematypes both sides of the edge: what a plug must send, and what the socket hands back.datais what a consumer reads, rendered for each integration. Itshostnameis the counter’s name on guestbook’s network.- Each job sees the edge as
integration.plug.dataandintegration.socket.data.pingproves the counter answers before anything is provisioned.
$ 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.
name: tallyversion: "1.0.0"title: Tallydescription: Counts in a key of guestbook's countercategory: demolicense: id: MITsocket: counterrequired: trueservices: - tallyschema: plug: key@string!: the key tally counts indata: key: tallyjobs: 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 }}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.
$ shc install ~/learn/tally -s tallyinstalling 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.
$ shc exec -s guestbook -S counter -- redis-cli get tally1$ shc exec -s tally -S tally -- sh -c 'redis-cli -h "$COUNTER_HOST" incr "$COUNTER_KEY"'2A 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.
$ shc update tally -i counter!updating deployment "tally"X200972RMVDON: -i removal counter matched this deployment and was applied to its persisted stateshc: [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 tally0A 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.
name: keyfrontversion: "1.0.0"title: Keyfrontdescription: Fronts an outside store and hands each consumer its keycategory: demolicense: id: MITvars: endpoint@url: the outside store's address accessKey@string: the store's access key secretKey@secret: the store's secret keyendpoint: https://store.learn.testaccessKey: learn-accesssecretKey: "ref+vault://store_secret?autogen"service: frontcredentials: - accessKey - secretKeyschema: socket: endpoint@string!: the store's address accessKey@string!: the key a consumer signs with secretKey@string!: its secretdata: endpoint: "{{ vars.endpoint }}" accessKey: "{{ vars.accessKey }}" secretKey: "{{ vars.secretKey }}"services: front: image: nginx:1.27-alpine expose: [80]$ 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.
$ shc update tally --connection llm=openai-teamNext: Add-ons.