Add smtp relation interface

README.md

@@ -45,6 +45,7 @@ To quickly get started, see the [template interface](https://github.com/canonica
 |               | [`auth_proxy`](interfaces/auth_proxy/v0/README.md)                           |  ![Status: Draft](https://img.shields.io/badge/Status-Draft-orange)   | 
 |               | [`openfga`](interfaces/openfga/v0/README.md)                                 |  ![Status: Live](https://img.shields.io/badge/Status-Live-darkgreen)  | 
 |               | [`saml`](interfaces/saml/v0/README.md)                                       |  ![Status: Live](https://img.shields.io/badge/Status-Live-darkgreen)   |
+|               | [`smtp`](interfaces/smtp/v0/README.md)                                       |  ![Status: Live](https://img.shields.io/badge/Status-Live-darkgreen)   |
 | Observability | [`grafana_auth`](interfaces/grafana_auth/v0/README.md)                       |  ![Status: Draft](https://img.shields.io/badge/Status-Draft-orange)   |
 |               | [`prometheus_remote_write`](interfaces/prometheus_remote_write/v0/README.md) |  ![Status: Live](https://img.shields.io/badge/Status-Live-darkgreen)  |
 |               | [`prometheus_scrape`](interfaces/prometheus_scrape/v0/README.md)             |  ![Status: Live](https://img.shields.io/badge/Status-Live-darkgreen)  |

docs/json_schemas/smtp/v0/provider.json

@@ -0,0 +1,129 @@
+{
+  "title": "ProviderSchema",
+  "description": "Provider schema for SMTP.",
+  "type": "object",
+  "properties": {
+    "unit": {
+      "$ref": "#/definitions/BaseModel"
+    },
+    "app": {
+      "$ref": "#/definitions/SmtpProviderData"
+    }
+  },
+  "required": [
+    "app"
+  ],
+  "definitions": {
+    "BaseModel": {
+      "title": "BaseModel",
+      "type": "object",
+      "properties": {}
+    },
+    "AuthType": {
+      "title": "AuthType",
+      "description": "Represent the auth type values.\n\nAttributes:\n    NONE: none\n    NOT_PROVIDED: not_provided\n    PLAIN: plain",
+      "enum": [
+        "none",
+        "not_provided",
+        "plain"
+      ],
+      "type": "string"
+    },
+    "TransportSecurity": {
+      "title": "TransportSecurity",
+      "description": "Represent the transport security values.\n\nAttributes:\n    NONE: none\n    STARTTLS: starttls\n    TLS: tls",
+      "enum": [
+        "none",
+        "starttls",
+        "tls"
+      ],
+      "type": "string"
+    },
+    "SmtpProviderData": {
+      "title": "SmtpProviderData",
+      "type": "object",
+      "properties": {
+        "host": {
+          "title": "Host",
+          "description": "SMTP host.",
+          "minLength": 1,
+          "examples": [
+            "example.smtp"
+          ],
+          "type": "string"
+        },
+        "port": {
+          "title": "Port",
+          "description": "SMTP port.",
+          "minimum": 1,
+          "maximum": 65536,
+          "examples": [
+            25
+          ],
+          "type": "integer"
+        },
+        "user": {
+          "title": "User",
+          "description": "SMTP user.",
+          "examples": [
+            "some_user"
+          ],
+          "type": "string"
+        },
+        "password": {
+          "title": "Password",
+          "description": "SMTP password.",
+          "examples": [
+            "somepasswd"
+          ],
+          "type": "string"
+        },
+        "password_id": {
+          "title": "Password ID",
+          "description": "Secret ID for the SMTP password.",
+          "examples": [
+            "secret:123213123123123123123"
+          ],
+          "type": "string"
+        },
+        "auth_type": {
+          "title": "Auth type",
+          "description": "The type used to authenticate with the SMTP relay.",
+          "examples": [
+            "none"
+          ],
+          "allOf": [
+            {
+              "$ref": "#/definitions/AuthType"
+            }
+          ]
+        },
+        "transport_security": {
+          "title": "Transport security",
+          "description": "The security protocol to use for the outgoing SMTP relay.",
+          "examples": [
+            "none"
+          ],
+          "allOf": [
+            {
+              "$ref": "#/definitions/TransportSecurity"
+            }
+          ]
+        },
+        "domain": {
+          "title": "Domain",
+          "description": "The domain used by the sent emails from SMTP relay.",
+          "examples": [
+            "domain"
+          ],
+          "type": "string"
+        }
+      },
+      "required": [
+        "host",
+        "auth_type",
+        "transport_security"
+      ]
+    }
+  }
+}

docs/json_schemas/smtp/v0/requirer.json

@@ -0,0 +1,20 @@
+{
+  "title": "RequirerSchema",
+  "description": "Requirer schema for SMTP.",
+  "type": "object",
+  "properties": {
+    "unit": {
+      "$ref": "#/definitions/BaseModel"
+    },
+    "app": {
+      "$ref": "#/definitions/BaseModel"
+    }
+  },
+  "definitions": {
+    "BaseModel": {
+      "title": "BaseModel",
+      "type": "object",
+      "properties": {}
+    }
+  }
+}

interfaces/smtp/v0/README.md

@@ -0,0 +1,64 @@
+# `smtp`
+
+## Overview
+
+This relation interface specification describes the expected behavior of charms integrating over the `smtp` Juju interface to provide or consume SMTP data.
+
+## Usage
+
+In most cases, this will be accomplished using the [smtp library](https://github.com/canonical/smtp-integrator-operator/blob/main/lib/charms/smtp_integrator/v0/smtp.py), although charm developers are free to provide alternative libraries as long as they fulfil the behavioural and schematic requirements described in this document.
+
+## Direction
+
+The `smtp` interface implements a provider/requirer pattern.
+The requirer is a charm that requires SMTP details to connect to an SMTP server, and the provider is a charm holding those details.
+
+```mermaid
+flowchart TD
+    Provider -- host, port, user, password_id, auth_type, transport_security, domain --> Requirer
+```
+
+or alternatively, if secrets are not supported by both sides
+
+```mermaid
+flowchart TD
+    Provider -- host, port, user, password, auth_type, transport_security, domain --> Requirer
+```
+
+## Behavior
+
+The requirer and the provider must adhere to a certain set of criteria to be considered compatible with the interface.
+
+### Provider
+
+- Is expected to publish the `host` in the relation databag.
+- Is expected to publish the `port` in the relation databag.
+- Is expected to publish the `auth_type` in the relation databag.
+- Is expected to publish the `transport_security` in the relation databag.
+
+### Requirer
+
+- Is not expected to publish anything
+
+## Relation Data
+
+### Provider
+
+[\[Pydantic Schema\]](./schema.py)
+
+Provider publishes the SMTP configuration. It should be placed in the **application** databag.
+
+#### Example
+
+```yaml
+related-units: {}
+application_data: {
+  "host": "example.smtp",
+  "port": "25",
+  "user": "example_user",
+  "password_id": "01548499c9233d4612352c989162d940f6a9e6f6d5cc058dfcf66f51575e09c2",
+  "auth_type": "plain",
+  "transport_security": "tls",
+  "domain": "domain",
+}
+```

interfaces/smtp/v0/charms.yaml

@@ -0,0 +1,6 @@
+providers:
+  - name: smtp-integrator
+    url: https://github.com/canonical/smtp-integrator-operator
+
+requirers:
+  []

interfaces/smtp/v0/interface_tests/test_provider.py

@@ -0,0 +1,19 @@
+# Copyright 2023 Canonical
+# See LICENSE file for licensing details.
+from interface_tester.interface_test import Tester
+from scenario import Relation, State
+
+
+def test_data_published_on_created():
+    t = Tester(
+        State(
+            relations=[
+                Relation(
+                    endpoint="smtp",
+                    interface="smtp",
+                )
+            ],
+        )
+    )
+    t.run("smtp-relation-created")
+    t.assert_schema_valid()

interfaces/smtp/v0/schema.py

@@ -0,0 +1,112 @@
+# Copyright 2023 Canonical
+# See LICENSE file for licensing details.
+"""This file defines the schema for the provider side of the smtp interface.
+
+It exposes one interfaces.schema_base.DataBagSchema subclass called:
+- ProviderSchema
+
+Examples:
+    ProviderSchema:
+        unit: <empty>
+        app: {"smtp":
+                 {
+                    "host": "example.smtp",
+                    "port": "25",
+                    "user": "example_user",
+                    "password_id": "01548499c9233d4612352c989162d940f6a9e6f6d5cc058dfcf66f51575e09c2",
+                    "auth_type": "plain",
+                    "transport_security": "tls",
+                    "domain": "domain",
+                }
+             }
+"""
+from enum import Enum
+from interface_tester.schema_base import DataBagSchema
+from pydantic import BaseModel, Field
+from typing import Optional
+
+
+class TransportSecurity(str, Enum):
+    """Represent the transport security values.
+
+    Attributes:
+        NONE: none
+        STARTTLS: starttls
+        TLS: tls
+    """
+
+    NONE = "none"
+    STARTTLS = "starttls"
+    TLS = "tls"
+
+
+class AuthType(str, Enum):
+    """Represent the auth type values.
+
+    Attributes:
+        NONE: none
+        NOT_PROVIDED: not_provided
+        PLAIN: plain
+    """
+
+    NONE = "none"
+    NOT_PROVIDED = "not_provided"
+    PLAIN = "plain"
+
+
+class SmtpProviderData(BaseModel):
+    host: str = Field(
+        ...,
+        min_length=1,
+        description="SMTP host.",
+        title="Host",
+        examples=["example.smtp"],
+    )
+    port: int = Field(
+        None,
+        ge=1,
+        le=65536,
+        description="SMTP port.",
+        title="Port",
+        examples=[25],
+    )
+    user: Optional[str] = Field(
+        description="SMTP user.",
+        title="User",
+        examples=["some_user"],
+    )
+    password: Optional[str] = Field(
+        description="SMTP password.",
+        title="Password",
+        examples=["somepasswd"],
+    )
+    password_id: Optional[str] = Field(
+        description="Juju secret ID for the SMTP password.",
+        title="Password ID",
+        examples=["secret:123213123123123123123"],
+    )
+    auth_type: AuthType = Field(
+        description="The type used to authenticate with the SMTP relay.",
+        title="Auth type",
+        examples=[AuthType.NONE],
+    )
+    transport_security: TransportSecurity = Field(
+        description="The security protocol to use for the outgoing SMTP relay.",
+        title="Transport security",
+        examples=[TransportSecurity.NONE],
+    )
+    domain: Optional[str] = Field(
+        description="The domain used by the sent emails from SMTP relay.",
+        title="Domain",
+        examples=["domain"],
+    )
+
+
+class ProviderSchema(DataBagSchema):
+    """Provider schema for SMTP."""
+
+    app: SmtpProviderData
+
+
+class RequirerSchema(DataBagSchema):
+    """Requirer schema for SMTP."""