Forge messaging module — send_jobs + per-provider credentials + sender + prompt_builder. Sprint 59.
| Tier | application |
| Role | unclassified (baselined) |
| Path | crates/application/messaging |
| Edition | 2024 |
| Targets | application_messaging, pg_forge_messaging |
| Public items | 46 across 9 modules |
| Tests | 8 |
What it is for
application-messaging — Layer 3 module. Sprint 59: services + workers extracted.
B-009: before this, migrations() returned Vec::new() and migrate_pending returned Ok(0) while ignoring the pool, so conversations/conversation_participants/chat_messages/send_jobs/ messaging_credentials (crates/infrastructure/communication/migrations/, files 000–004) were never created by anything that actually called this module's own migration path. application-messaging is the one forge-* module that consumes this schema directly (send_jobs via services::messaging, messaging_credentials via services::messaging_credentials, ChatMessage/conversation types via workers::sender's re-export) — application-communication re-exports the same infrastructure_communication crate but owns a distinct, unrelated communications timeline table of its own (crates/application/communication/migrations/0001_communication_init.sql), not this schema, so this wiring does not duplicate that crate's. infrastructure-ai's own 001_ai_credentials.sql (also a dependency of this crate, per Cargo.toml) is deliberately NOT vendored here: application-ai already owns and wires it (crates/application/ai/src/lib.rs), and vendoring the same file into a second module's ledger would double-apply it.
000_create_communication_tables.sql FKs conversation_participants and chat_messages to parties(id), and its triggers call update_updated_at_column() (crates/foundation/basemodels/migrations/001_base_model_infrastructure.sql, applied by the central platform set) — a host composing this module must apply those first, same ordering caveat application-calendar's own test documents. 001/002 are legacy person_id->party_id cleanup migrations that no-op gracefully on a fresh install (their own file headers say so); 003/004 (send_jobs, messaging_credentials) carry no FKs.
No permission_codes() added: neither infrastructure-communication (crates/infrastructure/communication/src/) nor infrastructure-ai defines permission/capability constants for this crate's own surface to draw from — nothing to wire without inventing names.
Capabilities
MessagingModule
application-messaging — Layer 3 module. Sprint 59: services + workers extracted.
| Item |
|---|
pub struct MessagingModule |
MessagingModule :: fn new() -> Self |
MessagingModule :: fn name(& self) -> & 'static str |
MessagingModule :: fn version(& self) -> & 'static str |
MessagingModule :: fn migrations(& self) -> Vec <MigrationSet> |
MessagingModule :: async fn migrate_pending(& self, pool : & PgPool) -> Result <u32, MigrationError> |
api (other)
application-messaging HTTP API. Sprint 65: extracted from rust-cms-engine.
| Item |
|---|
fn admin_router <S>() -> Router <S> where S : Clone + Send + Sync + 'static, PgPool : FromRef <S>, |
api::messaging_admin (other)
Messaging admin REST endpoints (Sprint 44 — Gate 1.5 Q3).
| Item |
|---|
fn router <S>() -> Router <S> where S : Clone + Send + Sync + 'static, PgPool : FromRef <S>, |
api::messaging_settings_admin (other)
Messaging settings admin REST endpoints (Sprint 50 → 53).
| Item |
|---|
fn router <S>() -> Router <S> where S : Clone + Send + Sync + 'static, PgPool : FromRef <S>, |
services::messaging (other)
Messaging service (Sprint 44).
| Item |
|---|
fn default_next_attempt_at(attempt_count : i32) -> DateTime <Utc> |
async fn enqueue_send(pool : & PgPool, req : EnqueueRequest) -> Result <SendJob, SendJobError> |
async fn get_send_job(pool : & PgPool, id : Uuid) -> Result <SendJob, SendJobError> |
async fn claim_pending(pool : & PgPool, channel : SendChannel, limit : i64,) -> Result <Vec <SendJob>, SendJobError> |
async fn mark_sent(pool : & PgPool, id : Uuid, provider_message_id : Option <& str>,) -> Result <SendJob, SendJobError> |
async fn mark_failed(pool : & PgPool, id : Uuid, error_class : & str, last_error : & str,) -> Result <SendJob, SendJobError> |
async fn bump_for_retry(pool : & PgPool, id : Uuid, next_attempt_at : DateTime <Utc>,) -> Result <SendJob, SendJobError> |
async fn fail_and_retry(pool : & PgPool, id : Uuid, error_class : & str, last_error : & str,) -> Result <SendJob, SendJobError> |
async fn list_jobs(pool : & PgPool, filter : ListJobsFilter,) -> Result <Vec <SendJobRow>, SendJobError> |
ListJobsFilter
Messaging service (Sprint 44).
| Item |
|---|
pub struct ListJobsFilter |
SendJobRow
Messaging service (Sprint 44).
| Item |
|---|
pub struct SendJobRow |
async fn latest_for_destination(pool : & PgPool, destination : & str,) -> Result <Option <SendJobRow>, SendJobError> |
services::messaging_credentials (other)
Messaging credentials service (Sprint 50).
| Item |
|---|
pub const KNOWN_PROVIDERS: & & str |
async fn test_smtp_connection(pool : & PgPool, tenant_id : Uuid, probe_to : Option <& str>,) -> Result <TestSmtpResult, MessagingSettingsError> |
MessagingSettingsError:MessagingSettingsError
Messaging credentials service (Sprint 50).
| Item |
|---|
pub enum MessagingSettingsError |
MessagingSettingsError:delete
Messaging credentials service (Sprint 50).
| Item |
|---|
async fn delete_tenant_provider_config(pool : & PgPool, tenant_id : Uuid, provider_kind : & str,) -> Result <(), MessagingSettingsError> |
async fn delete_system_provider_config(pool : & PgPool, provider_kind : & str,) -> Result <(), MessagingSettingsError> |
async fn delete_tenant_smtp(pool : & PgPool, tenant_id : Uuid,) -> Result <(), MessagingSettingsError> |
async fn delete_system_smtp(pool : & PgPool) -> Result <(), MessagingSettingsError> |
MessagingSettingsError:from
Messaging credentials service (Sprint 50).
| Item |
|---|
MessagingSettingsError :: fn from(e : MessagingCredentialsError) -> Self |
MessagingSettingsError:get
Messaging credentials service (Sprint 50).
| Item |
|---|
async fn get_tenant_provider_config(pool : & PgPool, tenant_id : Uuid, provider_kind : & str,) -> Result <Option <serde_json::Value>, MessagingSettingsError> |
async fn get_system_provider_config(pool : & PgPool, provider_kind : & str,) -> Result <Option <serde_json::Value>, MessagingSettingsError> |
async fn get_tenant_smtp(pool : & PgPool, tenant_id : Uuid,) -> Result <Option <SmtpConfig>, MessagingSettingsError> |
async fn get_system_smtp(pool : & PgPool) -> Result <Option <SmtpConfig>, MessagingSettingsError> |
MessagingSettingsError:list
Messaging credentials service (Sprint 50).
| Item |
|---|
async fn list_tenant_providers(pool : & PgPool, tenant_id : Uuid,) -> Result <Vec <MessagingProviderInfo>, MessagingSettingsError> |
async fn list_system_providers(pool : & PgPool,) -> Result <Vec <MessagingProviderInfo>, MessagingSettingsError> |
MessagingSettingsError:resolve
Messaging credentials service (Sprint 50).
| Item |
|---|
async fn resolve_smtp(pool : & PgPool, tenant_id : Uuid,) -> Result <Option <ResolvedConfig <SmtpConfig>>, MessagingSettingsError> |
MessagingSettingsError:set
Messaging credentials service (Sprint 50).
| Item |
|---|
async fn set_tenant_provider_config(pool : & PgPool, tenant_id : Uuid, provider_kind : & str, body : serde_json::Value,) -> Result <(), MessagingSettingsError> |
async fn set_system_provider_config(pool : & PgPool, provider_kind : & str, body : serde_json::Value,) -> Result <(), MessagingSettingsError> |
async fn set_tenant_smtp(pool : & PgPool, tenant_id : Uuid, config : & SmtpConfig,) -> Result <(), MessagingSettingsError> |
async fn set_system_smtp(pool : & PgPool, config : & SmtpConfig,) -> Result <(), MessagingSettingsError> |
TestSmtpResult
Messaging credentials service (Sprint 50).
| Item |
|---|
pub struct TestSmtpResult |
workers::messaging_worker (other)
Messaging worker loop (Sprint 46 + 51).
| Item |
|---|
fn default_messaging_registry() -> Arc <OutboundProviderRegistry> |
MessagingWorkerConfig
Messaging worker loop (Sprint 46 + 51).
| Item |
|---|
pub struct MessagingWorkerConfig |
MessagingWorkerConfig :: fn new(channel : SendChannel) -> Self |
async fn run_messaging_worker(pool : PgPool, sender : Arc <dyn MessageSender>, config : MessagingWorkerConfig, shutdown : CancellationToken,) |
async fn run_messaging_worker_with_registry(pool : PgPool, registry : Arc <OutboundProviderRegistry>, config : MessagingWorkerConfig, shutdown : CancellationToken,) |
How to use it
No examples/ target and no doctest in this crate's rustdoc. The tests listed under Verification are the closest executable usage.
Module structure
application_messaging
apiapi::messaging_adminapi::messaging_settings_adminservicesservices::messagingservices::messaging_credentialsworkersworkers::messaging_workerworkers::sender
flowchart TD n_application_messaging["application_messaging"] n_application_messaging --> n_api["api"] n_api --> n_api__messaging_admin["messaging_admin"] n_api --> n_api__messaging_settings_admin["messaging_settings_admin"] n_application_messaging --> n_services["services"] n_services --> n_services__messaging["messaging"] n_services --> n_services__messaging_credentials["messaging_credentials"] n_application_messaging --> n_workers["workers"] n_workers --> n_workers__messaging_worker["messaging_worker"] n_workers --> n_workers__sender["sender"]
Public surface
`crate root`
| Item | What it is |
|---|---|
pub struct MessagingModule | — |
MessagingModule :: fn new() -> Self | — |
MessagingModule :: fn name(& self) -> & 'static str | — |
MessagingModule :: fn version(& self) -> & 'static str | — |
MessagingModule :: fn migrations(& self) -> Vec <MigrationSet> | — |
MessagingModule :: async fn migrate_pending(& self, pool : & PgPool) -> Result <u32, MigrationError> | — |
`api`
| Item | What it is |
|---|---|
fn admin_router <S>() -> Router <S> where S : Clone + Send + Sync + 'static, PgPool : FromRef <S>, | Merge all admin-scoped messaging routers into one, generic over S. |
`api::messaging_admin`
| Item | What it is |
|---|---|
fn router <S>() -> Router <S> where S : Clone + Send + Sync + 'static, PgPool : FromRef <S>, | — |
`api::messaging_settings_admin`
| Item | What it is |
|---|---|
fn router <S>() -> Router <S> where S : Clone + Send + Sync + 'static, PgPool : FromRef <S>, | — |
`services::messaging`
| Item | What it is |
|---|---|
fn default_next_attempt_at(attempt_count : i32) -> DateTime <Utc> | Default retry backoff: returns the next attempt time for a given attempt count |
async fn enqueue_send(pool : & PgPool, req : EnqueueRequest) -> Result <SendJob, SendJobError> | — |
async fn get_send_job(pool : & PgPool, id : Uuid) -> Result <SendJob, SendJobError> | — |
async fn claim_pending(pool : & PgPool, channel : SendChannel, limit : i64,) -> Result <Vec <SendJob>, SendJobError> | — |
async fn mark_sent(pool : & PgPool, id : Uuid, provider_message_id : Option <& str>,) -> Result <SendJob, SendJobError> | — |
async fn mark_failed(pool : & PgPool, id : Uuid, error_class : & str, last_error : & str,) -> Result <SendJob, SendJobError> | — |
async fn bump_for_retry(pool : & PgPool, id : Uuid, next_attempt_at : DateTime <Utc>,) -> Result <SendJob, SendJobError> | — |
async fn fail_and_retry(pool : & PgPool, id : Uuid, error_class : & str, last_error : & str,) -> Result <SendJob, SendJobError> | Convenience: mark failed AND schedule a retry using the default backoff |
pub struct ListJobsFilter | — |
pub struct SendJobRow | — |
async fn list_jobs(pool : & PgPool, filter : ListJobsFilter,) -> Result <Vec <SendJobRow>, SendJobError> | — |
async fn latest_for_destination(pool : & PgPool, destination : & str,) -> Result <Option <SendJobRow>, SendJobError> | — |
`services::messaging_credentials`
| Item | What it is |
|---|---|
pub const KNOWN_PROVIDERS: & & str | The list of provider kinds Sprint 0.19/52 ships builders for |
pub enum MessagingSettingsError | — |
MessagingSettingsError :: fn from(e : MessagingCredentialsError) -> Self | — |
async fn set_tenant_provider_config(pool : & PgPool, tenant_id : Uuid, provider_kind : & str, body : serde_json::Value,) -> Result <(), MessagingSettingsError> | — |
async fn set_system_provider_config(pool : & PgPool, provider_kind : & str, body : serde_json::Value,) -> Result <(), MessagingSettingsError> | — |
async fn get_tenant_provider_config(pool : & PgPool, tenant_id : Uuid, provider_kind : & str,) -> Result <Option <serde_json::Value>, MessagingSettingsError> | — |
async fn get_system_provider_config(pool : & PgPool, provider_kind : & str,) -> Result <Option <serde_json::Value>, MessagingSettingsError> | — |
async fn delete_tenant_provider_config(pool : & PgPool, tenant_id : Uuid, provider_kind : & str,) -> Result <(), MessagingSettingsError> | — |
async fn delete_system_provider_config(pool : & PgPool, provider_kind : & str,) -> Result <(), MessagingSettingsError> | — |
async fn set_tenant_smtp(pool : & PgPool, tenant_id : Uuid, config : & SmtpConfig,) -> Result <(), MessagingSettingsError> | — |
async fn get_tenant_smtp(pool : & PgPool, tenant_id : Uuid,) -> Result <Option <SmtpConfig>, MessagingSettingsError> | — |
async fn delete_tenant_smtp(pool : & PgPool, tenant_id : Uuid,) -> Result <(), MessagingSettingsError> | — |
async fn set_system_smtp(pool : & PgPool, config : & SmtpConfig,) -> Result <(), MessagingSettingsError> | — |
async fn get_system_smtp(pool : & PgPool) -> Result <Option <SmtpConfig>, MessagingSettingsError> | — |
async fn delete_system_smtp(pool : & PgPool) -> Result <(), MessagingSettingsError> | — |
async fn list_tenant_providers(pool : & PgPool, tenant_id : Uuid,) -> Result <Vec <MessagingProviderInfo>, MessagingSettingsError> | — |
async fn list_system_providers(pool : & PgPool,) -> Result <Vec <MessagingProviderInfo>, MessagingSettingsError> | — |
async fn resolve_smtp(pool : & PgPool, tenant_id : Uuid,) -> Result <Option <ResolvedConfig <SmtpConfig>>, MessagingSettingsError> | Used by the messaging worker / outbound senders when about to dispatch on behalf of a tenant |
pub struct TestSmtpResult | — |
async fn test_smtp_connection(pool : & PgPool, tenant_id : Uuid, probe_to : Option <& str>,) -> Result <TestSmtpResult, MessagingSettingsError> | Resolve the SMTP config + construct a sender + attempt to send a tiny probe message to a caller-supplied address |
`workers::messaging_worker`
| Item | What it is |
|---|---|
fn default_messaging_registry() -> Arc <OutboundProviderRegistry> | Build a default registry pre-registered with the SMTP builder |
pub struct MessagingWorkerConfig | — |
MessagingWorkerConfig :: fn new(channel : SendChannel) -> Self | — |
async fn run_messaging_worker(pool : PgPool, sender : Arc <dyn MessageSender>, config : MessagingWorkerConfig, shutdown : CancellationToken,) | Run the messaging worker until the cancellation token fires |
async fn run_messaging_worker_with_registry(pool : PgPool, registry : Arc <OutboundProviderRegistry>, config : MessagingWorkerConfig, shutdown : CancellationToken,) | Run the messaging worker with per-tenant credential resolution via the upstream OutboundProviderRegistry |
Re-exports. Exported here, defined elsewhere.
| Export | Defined in |
|---|---|
SendJobStatus | infrastructure_communication::SendJobStatus |
{AlwaysFailOutboundSenderasAlwaysFailSender,OutboundErrorasSenderError,OutboundOutcomeasSendOutcome,OutboundSenderasMessageSender,StubOutboundSenderasStubMessageSender,} | infrastructure_communication::{AlwaysFailOutboundSenderasAlwaysFailSender,OutboundErrorasSenderError,OutboundOutcomeasSendOutcome,OutboundSenderasMessageSender,StubOutboundSenderasStubMessageSender,} |
Boundary
Reaches into infrastructure, platform.
Shares tier application with 120 other crates: application-agreements, application-ai, application-analytics, application-approvals, application-assessments, application-audit-log, application-auth, application-billing, … (120 total).
_What this crate deliberately does NOT own is a judgment. No committed registry records one for it, so none is stated here._
Where it sits
| Tier (ontology) | application |
| Architectural role (taxonomy) | unclassified (baselined) |
| Location | crates/application/messaging |
| Vocabulary in force (lexicon) | current |
Tier flow. Which tiers this crate's own edges cross.
flowchart LR n_application["application"] --> n_infrastructure["infrastructure"] n_application["application"] --> n_platform["platform"]
Dependencies
Runtime, in this workspace.
| Crate | Tier | Optional | Only on |
|---|---|---|---|
| `application-core` | application | no | always |
| `application-rbac` | application | no | always |
| `infrastructure-ai` | infrastructure | no | always |
| `infrastructure-communication` | infrastructure | no | always |
| `platform-dto` | platform | no | always |
Runtime, from outside the workspace.
| Crate | Requirement | Features | Optional | Only on |
|---|---|---|---|---|
async-trait | ^0.1 | — | no | always |
axum | ^0.7 | multipart | no | always |
chrono | ^0.4 | serde | no | always |
futures-util | ^0.3 | — | no | always |
serde | ^1 | derive | no | always |
serde_json | ^1 | — | no | always |
sqlx | ^0.8 | runtime-tokio, postgres, chrono, uuid, json | no | always |
thiserror | ^2 | — | no | always |
tokio | ^1 | full | no | always |
tokio-util | ^0.7 | rt | no | always |
tracing | ^0.1 | — | no | always |
uuid | ^1 | v4, v7, serde, js | no | always |
Development, in this workspace.
| Crate | Tier | Optional | Only on |
|---|---|---|---|
| `application-engine` | application | no | always |
| `application-parties` | application | no | always |
Build. None.
Depended on by. Nothing in this workspace.
Signal flow — what reaches this crate, and what it reaches.
flowchart LR SELF["application-messaging"] SELF -->|development| n_application_engine["application-engine"] SELF -->|development| n_application_parties["application-parties"] SELF -->|runtime| n_application_core["application-core"] SELF -->|runtime| n_application_rbac["application-rbac"] SELF -->|runtime| n_infrastructure_ai["infrastructure-ai"] SELF -->|runtime| n_infrastructure_communication["infrastructure-communication"] SELF -->|runtime| n_platform_dto["platform-dto"] classDef self fill:#1f883d,stroke:#1f883d,color:#fff; class SELF self;
Feature flags
No Cargo features are defined: every capability is unconditional, so no consumer can receive a half-wired crate.
Targets
| Kind | Name | Source |
|---|---|---|
| lib | application_messaging | `src/lib.rs` |
| test | pg_forge_messaging | `tests/pg_forge_messaging.rs` |
Error model
| Error type | Named by |
|---|---|
MessagingSettingsError | delete_system_provider_config, delete_system_smtp, delete_tenant_provider_config, delete_tenant_smtp, get_system_provider_config, get_system_smtp, … (16 total) |
Operational characteristics
| Property | Evidence |
|---|---|
| async public surface | yes |
| async runtime | yes |
| database access | yes |
| network I/O | yes |
| unsafe code | none detected |
| environment variables | yes |
No unsafe block, unsafe fn, unsafe impl or unsafe trait was found by the parser anywhere in this crate's source.
Configuration
| Variable | Read in |
|---|---|
CARGO_PKG_VERSION | src/lib.rs |
Related capabilities
No workspace crate depends on this one.
Verification
| Kind | Count |
|---|---|
| Unit tests | 7 |
| Integration tests | 1 |
| Examples | 0 |
| Doctests | 0 |
Evidence by module. How often each public module is named by something executable.
| Module | Tests | Examples | Consumers |
|---|---|---|---|
crate root | 1 | 0 | 0 |
api | 1 | 0 | 0 |
api::messaging_admin | 1 | 0 | 0 |
api::messaging_settings_admin | 1 | 0 | 0 |
services::messaging | 12 | 0 | 0 |
services::messaging_credentials | 19 | 0 | 0 |
workers::messaging_worker | 4 | 0 | 0 |
What the tests establish, by name:
migrate_pending_creates_send_jobs_table—tests/pg_forge_messaging.rsa_caller_with_no_memberships_is_denied—src/api/messaging_settings_admin.rsa_member_may_act_on_their_own_tenant—src/api/messaging_settings_admin.rsa_non_member_may_not_act_on_another_tenant—src/api/messaging_settings_admin.rsa_platform_global_actor_may_act_on_any_tenant—src/api/messaging_settings_admin.rsmembership_in_one_tenant_does_not_grant_a_sibling—src/api/messaging_settings_admin.rstest_module_migrations_non_empty—src/lib.rsdefault_backoff_grows_then_caps—src/services/messaging.rs
Documentation coverage
| Measure | Documented | Total |
|---|---|---|
| Public items with rustdoc | 9 | 46 |
Public modules with a //! block | 7 | 9 |
pie showData
title Public items with rustdoc
"Documented" : 9
"No rustdoc detected" : 37
Metrics
| Metric | Value |
|---|---|
| Rust source files | 10 |
| Source lines | 1407 |
| Code lines | 1041 |
| Public API items | 46 |
| Public modules | 9 |
| Tests | 8 |
| Examples | 0 |
| Cargo features | 0 |
| Direct runtime dependencies | 17 |
| Workspace reverse dependencies | 0 |
pie showData
title Public API by kind
"constant" : 1
"enum" : 1
"function" : 32
"method" : 7
"struct" : 5
pie showData
title Rust source composition
"Code" : 1041
"Blank or comment" : 366
Generation
Rendered by tools-corpus corpus readme from repository evidence alone, renderer schema 2, lexicon current. No model, network service or database was consulted. Regenerate with tools-corpus corpus readme --write; verify with --check.