<a id="exp-interface-concepts"></a>

# Interface concepts

<!-- @artefact SDK -->
<!-- @artefact interface -->

Interfaces are a mechanism for communication and resource sharing.
It is an integral part of workshop confinement,
ensuring that each workshop operates in its own isolated environment,
while still allowing controlled interactions among the SDKs and with the host.

In **Workshop**, SDKs can act as providers and consumers of resources
such as the GPU, or file directories.
Host system resources
are exposed via the [system SDK](https://ubuntu.com/workshop/docs//explanation/sdks/concepts.md#exp-system-sdk)
that is present in every workshop by design.

For a workshop to be operational, the SDKs listed in its definition
must *connect* to the resources they expect.
Such connections are uniformly established via the interface system.

To achieve this, **Workshop** implements a counterpart to **snapd**’s
[interface manager](https://snapcraft.io/docs/interface-management/),
which controls whether an SDK can use resources beyond its confines.
You can think of specific interfaces as resource *types*:
filesystem, hardware, computing, and so on.

Specific interfaces are predefined and implemented by **Workshop**,
so you cannot create a custom interface type.
Currently, **Workshop** and **SDKcraft** support the following:

- [Camera interface](https://ubuntu.com/workshop/docs//explanation/interfaces/camera-interface.md#exp-camera-interface) (manually connected)
- [Custom device interface](https://ubuntu.com/workshop/docs//explanation/interfaces/custom-device-interface.md#exp-custom-device-interface) (manually connected)
- [Desktop interface](https://ubuntu.com/workshop/docs//explanation/interfaces/desktop-interface.md#exp-desktop-interface) (manually connected)
- [GPU interface](https://ubuntu.com/workshop/docs//explanation/interfaces/gpu-interface.md#exp-gpu-interface) (auto-connected)
- [Mount interface](https://ubuntu.com/workshop/docs//explanation/interfaces/mount-interface.md#exp-mount-interface) (auto-connected)
- [SSH interface](https://ubuntu.com/workshop/docs//explanation/interfaces/ssh-interface.md#exp-ssh-interface) (manually connected)

<a id="exp-plugs-slots"></a>

## Plugs and slots

To make use of these interfaces,
SDKs and [workshops](https://ubuntu.com/workshop/docs//explanation/workshops/concepts.md#exp-workshop-definition-connections) define *slots*.
For example, a [mount interface](https://ubuntu.com/workshop/docs//explanation/interfaces/mount-interface.md#exp-mount-interface) slot
creates a source directory to be mounted inside the workshop via a plug.

Further, SDKs and [workshops](https://ubuntu.com/workshop/docs//explanation/workshops/concepts.md#exp-workshop-definition-connections) define *plugs*
to connect to a slot of a certain interface type.
For example, a [mount interface](https://ubuntu.com/workshop/docs//explanation/interfaces/mount-interface.md#exp-mount-interface) plug
mounts the slot to a target directory inside the workshop.

You can think of the plug as the recipient of the resources exposed by the slot;
note that a slot can handle connections with multiple plugs.

Connections can be established:

- Automatically:
  By running **workshop launch**, **workshop refresh**,
  or **workshop start**.
- Manually:
  By running **workshop connect** after the workshop has started,
  or by listing connections in the
  [workshop definition](https://ubuntu.com/workshop/docs//explanation/workshops/concepts.md#exp-workshop-definition-connections)
  and running **workshop refresh**.

All connections are subject to validation.
Also, automatic connections require plugs and slots to have matching details
and aren’t allowed for some interfaces, such as `ssh-agent`.
Finally, the order of automatic connections is not guaranteed,
so you should not rely on it.

<a id="exp-interfaces-validation"></a>

## Validation

All plugs and slots defined for a workshop directly or via its SDKs are checked
to make sure they can be installed as part of the workshop and then connected.
For this, **Workshop** uses a set of internal rules.

Each interface has its own rule set;
for example, the mount interface plug can be installed and auto-connected
based on its rules alone.
However, other interfaces may have different rules,
such as allowing installation but not auto-connection for `ssh-agent`.

<a id="exp-interface-connections"></a>

## Connections

<!-- @artefact interface connection -->

From the user perspective,
connections can be established through the interface system in several ways:

- The `connections` section of the workshop definition
  and the **workshop connect** command
  can be used to link interface plugs to respective slots,
  allowing the SDKs to orderly access the resources.
- Conversely, the **workshop disconnect** command
  terminates existing interface connections,
  revoking the access to the resources granted by the connection.
- Finally, the **workshop connections** command
  lists all existing connections and their states,
  providing an overview of how workshop connections are laid out.

Some plugs can be auto-connected to their slots at launch or refresh.
This behavior varies by interface,
but the overall aim is to conduct reasonably in each case:
the [mount](https://ubuntu.com/workshop/docs//explanation/interfaces/mount-interface.md#exp-mount-interface)
and the [GPU](https://ubuntu.com/workshop/docs//explanation/interfaces/gpu-interface.md#exp-gpu-interface) interfaces are auto-connected,
whereas the [camera](https://ubuntu.com/workshop/docs//explanation/interfaces/camera-interface.md#exp-camera-interface),
[custom device](https://ubuntu.com/workshop/docs//explanation/interfaces/custom-device-interface.md#exp-custom-device-interface),
[desktop](https://ubuntu.com/workshop/docs//explanation/interfaces/desktop-interface.md#exp-desktop-interface), and [SSH](https://ubuntu.com/workshop/docs//explanation/interfaces/ssh-interface.md#exp-ssh-interface)
interfaces require manual connection.

To know how each kind of connection is treated
when a workshop is launched, refreshed, or restored,
see [Connections across refresh and restore](https://ubuntu.com/workshop/docs//explanation/workshops/concepts.md#exp-workshop-connection-lifecycle).

<a id="exp-plug-bindings"></a>

## Plug bindings

SDKs usually access host resources via [interface plugs](#exp-plugs-slots).
When multiple SDKs try to use the same resource in conflicting ways,
the workshop won’t launch and shows an error.

To fix this issue, you can bind one plug to another of the same interface type.
This makes both plugs point to the same resource without conflicts.
Any action performed on one plug (like mounting or remounting)
thus automatically applies to *all* bound plugs.

When you run **workshop connections**,
a bound plug will have `bind` listed under `Notes`,
along with the line number of the target plug:

<!-- @artefact workshop connections -->
```console
$ workshop connections digits

  INTERFACE  PLUG                    SLOT                 NOTES
  mount      digits/torchaudio:hub   digits/system:mount  bind.1
  mount      digits/torchvision:hub  digits/system:mount  bind.1
```

Here, both plugs are listed as `bind.1`,
pointing to `torchaudio:hub` in the *first* line.

<a id="exp-interfaces-cli-operations"></a>

## Related CLI operations

A number of basic workshop operations
affect plugs and slots in different ways.

<!-- @artefact workshop launch -->

When you **workshop launch** a workshop,
an auto-connect task handles each interface plug,
finding a candidate slot,
verifying the plug’s eligibility for the slot based on their declarations
and connecting the two.

<!-- @artefact workshop refresh -->

On **workshop refresh**,
existing connections are preserved in the refreshed workshop
if their plugs were connected before the operation.
A newer version of an SDK may drop a plug that was previously connected;
such connections are removed,
but the host-based content remains.

<!-- @artefact interface connection -->

On **workshop remove**,
both the interface connections and the default host directories
(if any have been created, for example, to accommodate mount interface slots)
are removed.

Also, you can manually enable or disable connections
with **workshop connect** and **workshop disconnect**,
whereas **workshop connections** can list all connections
that have been established by any **Workshop** projects.

#### NOTE
We remove content stored in our default locations
because it’s not a good idea to keep user data forever.
Thus, at least some commands will delete this data
to prevent it from piling up in hidden places
where it’s unlikely to be used again.

## See also

Explanation:

- [SDKs](https://ubuntu.com/workshop/docs//explanation/index.md#exp-sdks)
- [Workshops and projects](https://ubuntu.com/workshop/docs//explanation/index.md#exp-workshop)

How-to guides:

- [How to fix plug conflicts with binding](https://ubuntu.com/workshop/docs//how-to/fix-workshops/resolve-plug-conflicts.md#how-resolve-plug-conflicts)

Reference:

- [Command-line interfaces](https://ubuntu.com/workshop/docs//reference/index.md#ref-cli)
- [workshop connect](https://ubuntu.com/workshop/docs//reference/cli/workshop.md#ref-workshop-connect)
- [workshop connections](https://ubuntu.com/workshop/docs//reference/cli/workshop.md#ref-workshop-connections)
- [Workshop definition](https://ubuntu.com/workshop/docs//reference/definition-files/workshop-definition.md#ref-workshop-definition)
- [workshop disconnect](https://ubuntu.com/workshop/docs//reference/cli/workshop.md#ref-workshop-disconnect)
- [workshop info](https://ubuntu.com/workshop/docs//reference/cli/workshop.md#ref-workshop-info)
- [workshop launch](https://ubuntu.com/workshop/docs//reference/cli/workshop.md#ref-workshop-launch)
- [workshop refresh](https://ubuntu.com/workshop/docs//reference/cli/workshop.md#ref-workshop-refresh)
- [workshop remove](https://ubuntu.com/workshop/docs//reference/cli/workshop.md#ref-workshop-remove)