Skip to content

ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.

refactor(unify): §6 Phase C6a — email provider usage flags

Juan Denis45e01f87319d
diff --git a/backend/app/models/email_provider.py b/backend/app/models/email_provider.py
index fd032f48..650e12ca 100644
--- a/backend/app/models/email_provider.py
+++ b/backend/app/models/email_provider.py
@@ -29,6 +29,13 @@ class EmailProviderConnection(db.Model):
is_default = db.Column(db.Boolean, default=False, index=True)
is_active = db.Column(db.Boolean, default=True)
+ # Usage flags (§6 unification): one connection can power the Notification Bus
+ # and/or the Postfix outbound relay. API providers (SendGrid/Postmark/SES/
+ # Mailgun) can't be a Postfix smarthost, so only 'smtp' rows set uses_relay.
+ uses_notifications = db.Column(db.Boolean, default=True, nullable=False)
+ uses_relay = db.Column(db.Boolean, default=False, nullable=False)
+ relay_priority = db.Column(db.Integer, default=0, nullable=False)
+
created_by = db.Column(db.Integer, db.ForeignKey('users.id'), nullable=True)
created_at = db.Column(db.DateTime, default=datetime.utcnow)
updated_at = db.Column(db.DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
@@ -59,6 +66,9 @@ class EmailProviderConnection(db.Model):
'from_name': self.from_name,
'is_default': self.is_default,
'is_active': self.is_active,
+ 'uses_notifications': self.uses_notifications,
+ 'uses_relay': self.uses_relay,
+ 'relay_priority': self.relay_priority,
'configured_fields': sorted(creds.keys()),
'created_at': self.created_at.isoformat() if self.created_at else None,
'last_tested_at': self.last_tested_at.isoformat() if self.last_tested_at else None,
diff --git a/backend/app/notifications/providers.py b/backend/app/notifications/providers.py
index 409f87c8..4db09f16 100644
--- a/backend/app/notifications/providers.py
+++ b/backend/app/notifications/providers.py
@@ -75,14 +75,28 @@ class EmailProviderService:
@classmethod
def default_provider(cls):
- """The active default provider, or the first active one, or None."""
- row = EmailProviderConnection.query.filter_by(is_default=True, is_active=True).first()
+ """The provider the Notification Bus should send through: the active
+ default, else the first active one — both restricted to providers
+ flagged ``uses_notifications`` so relay-only rows are never picked (§6)."""
+ row = EmailProviderConnection.query.filter_by(
+ is_default=True, is_active=True, uses_notifications=True).first()
if row:
return row
- return EmailProviderConnection.query.filter_by(is_active=True).order_by(
+ return EmailProviderConnection.query.filter_by(
+ is_active=True, uses_notifications=True).order_by(
EmailProviderConnection.created_at.asc()
).first()
+ @classmethod
+ def relay_provider(cls):
+ """The active SMTP connection that should drive the Postfix relay:
+ highest relay_priority first, then oldest. None if no relay is flagged."""
+ return EmailProviderConnection.query.filter_by(
+ uses_relay=True, is_active=True).order_by(
+ EmailProviderConnection.relay_priority.desc(),
+ EmailProviderConnection.created_at.asc(),
+ ).first()
+
@classmethod
def add_provider(cls, data, user_id=None):
provider = (data.get('provider') or '').lower().strip()
@@ -106,6 +120,9 @@ class EmailProviderService:
if make_default:
EmailProviderConnection.query.update({EmailProviderConnection.is_default: False})
+ # Usage flags (§6). API providers cannot be a Postfix smarthost, so
+ # uses_relay is only honored for SMTP.
+ uses_relay = bool(data.get('uses_relay')) and provider == 'smtp'
row = EmailProviderConnection(
provider=provider,
name=data.get('name') or spec['name'],
@@ -114,6 +131,9 @@ class EmailProviderService:
from_name=(data.get('from_name') or 'ServerKit').strip(),
is_default=make_default,
is_active=data.get('is_active', True),
+ uses_notifications=bool(data.get('uses_notifications', True)),
+ uses_relay=uses_relay,
+ relay_priority=int(data.get('relay_priority') or 0),
created_by=user_id,
)
db.session.add(row)
diff --git a/backend/migrations/versions/038_email_provider_usage_flags.py b/backend/migrations/versions/038_email_provider_usage_flags.py
new file mode 100644
index 00000000..93e184f3
--- /dev/null
+++ b/backend/migrations/versions/038_email_provider_usage_flags.py
@@ -0,0 +1,57 @@
+"""Email provider usage flags (§6 unification).
+
+Adds to email_provider_connections:
+- uses_notifications (bool, default true)
+- uses_relay (bool, default false)
+- relay_priority (int, default 0)
+
+So a single connection can drive both the Notification Bus and the Postfix
+outbound relay, retiring the separate single-row email_relay_config.
+
+Idempotent: MigrationService runs _fix_missing_columns() + db.create_all() on
+boot before Alembic, so guard on the live schema.
+
+Revision ID: 038_email_provider_usage_flags
+Revises: 037_backup_target_types
+Create Date: 2026-06-24
+"""
+from alembic import op
+import sqlalchemy as sa
+
+revision = '038_email_provider_usage_flags'
+down_revision = '037_backup_target_types'
+branch_labels = None
+depends_on = None
+
+TABLE = 'email_provider_connections'
+
+
+def _add_col(inspector, col, column):
+ if TABLE in inspector.get_table_names():
+ cols = {c['name'] for c in inspector.get_columns(TABLE)}
+ if col not in cols:
+ op.add_column(TABLE, column)
+
+
+def _drop_col(inspector, col):
+ if TABLE in inspector.get_table_names():
+ cols = {c['name'] for c in inspector.get_columns(TABLE)}
+ if col in cols:
+ op.drop_column(TABLE, col)
+
+
+def upgrade():
+ inspector = sa.inspect(op.get_bind())
+ _add_col(inspector, 'uses_notifications',
+ sa.Column('uses_notifications', sa.Boolean(), nullable=False, server_default=sa.true()))
+ _add_col(inspector, 'uses_relay',
+ sa.Column('uses_relay', sa.Boolean(), nullable=False, server_default=sa.false()))
+ _add_col(inspector, 'relay_priority',
+ sa.Column('relay_priority', sa.Integer(), nullable=False, server_default='0'))
+
+
+def downgrade():
+ inspector = sa.inspect(op.get_bind())
+ _drop_col(inspector, 'relay_priority')
+ _drop_col(inspector, 'uses_relay')
+ _drop_col(inspector, 'uses_notifications')
diff --git a/backend/tests/test_email_provider_usage_flags.py b/backend/tests/test_email_provider_usage_flags.py
new file mode 100644
index 00000000..dd32efbe
--- /dev/null
+++ b/backend/tests/test_email_provider_usage_flags.py
@@ -0,0 +1,61 @@
+"""§6 Phase C6a — email provider usage flags.
+
+One EmailProviderConnection can drive the Notification Bus and/or the Postfix
+relay. Notification selection ignores relay-only rows; a relay selector picks
+the flagged SMTP connection by priority.
+"""
+from app.models.email_provider import EmailProviderConnection
+from app.notifications.providers import EmailProviderService
+
+
+def test_usage_flags_default_and_serialize(app):
+ with app.app_context():
+ p = EmailProviderService.add_provider({
+ 'provider': 'smtp', 'name': 'Main SMTP',
+ 'host': 'smtp.example.com', 'port': 587, 'username': 'u', 'password': 'pw',
+ })
+ d = p.to_dict()
+ assert d['uses_notifications'] is True
+ assert d['uses_relay'] is False
+ assert d['relay_priority'] == 0
+
+
+def test_default_provider_ignores_relay_only(app):
+ with app.app_context():
+ # A relay-only row must never be chosen for notifications.
+ EmailProviderService.add_provider({
+ 'provider': 'smtp', 'name': 'Relay only',
+ 'host': 'relay.example.com', 'port': 587, 'username': 'u', 'password': 'pw',
+ 'uses_notifications': False, 'uses_relay': True, 'is_default': True,
+ })
+ assert EmailProviderService.default_provider() is None
+
+ notif = EmailProviderService.add_provider({
+ 'provider': 'sendgrid', 'name': 'SG', 'api_key': 'sg-key',
+ })
+ chosen = EmailProviderService.default_provider()
+ assert chosen is not None and chosen.id == notif.id
+
+
+def test_relay_provider_selection_by_priority(app):
+ with app.app_context():
+ low = EmailProviderService.add_provider({
+ 'provider': 'smtp', 'name': 'low', 'host': 'a', 'username': 'u', 'password': 'p',
+ 'uses_relay': True, 'relay_priority': 1, 'uses_notifications': False,
+ })
+ high = EmailProviderService.add_provider({
+ 'provider': 'smtp', 'name': 'high', 'host': 'b', 'username': 'u', 'password': 'p',
+ 'uses_relay': True, 'relay_priority': 5, 'uses_notifications': False,
+ })
+ chosen = EmailProviderService.relay_provider()
+ assert chosen.id == high.id
+ assert low.id != high.id
+
+
+def test_api_provider_cannot_be_relay(app):
+ with app.app_context():
+ # uses_relay requested on a non-SMTP provider is ignored.
+ p = EmailProviderService.add_provider({
+ 'provider': 'sendgrid', 'name': 'SG', 'api_key': 'k', 'uses_relay': True,
+ })
+ assert p.uses_relay is False