Use diagnostic attrs for ABI/SQL-related traits (pgcentralfoundation#2203)

We use the attributes to hide `FunctionMetadata` from diagnostic output,
as it is a "behind the scenes" trait, and emphasize `SqlTranslatable`.
We also comment briefly on why `ArgAbi<'_>` and `RetAbi` are like they
are. This significantly improves the diagnostics for all of these by
massively cutting down on noise generated while flailing around.

Author: workingjubilee

pgrx-sql-entity-graph/src/metadata/function_metadata.rs

@@ -42,6 +42,7 @@ pub trait FunctionMetadata<A> {
 
 macro_rules! impl_fn {
     ($($A:ident),* $(,)?) => {
+        #[diagnostic::do_not_recommend]
         impl<$($A,)* R, F> FunctionMetadata<($($A,)*)> for F
         where
             $($A: SqlTranslatable,)*
@@ -56,6 +57,8 @@ macro_rules! impl_fn {
                 }
             }
         }
+
+        #[diagnostic::do_not_recommend]
         impl<$($A,)* R> FunctionMetadata<($($A,)*)> for unsafe fn($($A,)*) -> R
         where
             $($A: SqlTranslatable,)*

pgrx-sql-entity-graph/src/metadata/sql_translatable.rs

@@ -70,6 +70,10 @@ or the Rust handling in PGRX may emit undefined behavior.
 It cannot be made private or sealed due to details of the structure of the PGRX framework.
 Nonetheless, if you are not confident the translation is valid: do not implement this trait.
 */
+#[diagnostic::on_unimplemented(
+    message = "`{Self}` has no representation in SQL",
+    label = "non-SQL type"
+)]
 pub unsafe trait SqlTranslatable {
     fn type_name() -> &'static str {
         core::any::type_name::<Self>()

pgrx-tests/tests/compile-fail/u32.rs

@@ -0,0 +1,8 @@
+use pgrx::prelude::*;
+
+fn main() {}
+
+#[pg_extern]
+pub fn whatever(a: u32) -> u32 {
+    a
+}

pgrx-tests/tests/compile-fail/u32.stderr

@@ -0,0 +1,78 @@
+error[E0277]: the trait bound `fn(u32) -> u32: FunctionMetadata<_>` is not satisfied
+ --> tests/compile-fail/u32.rs:6:5
+  |
+5 | #[pg_extern]
+  | ------------ in this procedural macro expansion
+6 | pub fn whatever(a: u32) -> u32 {
+  |     ^^ the trait `FunctionMetadata<_>` is not implemented for `fn(u32) -> u32`
+  |
+  = note: this error originates in the attribute macro `pg_extern` (in Nightly builds, run with -Z macro-backtrace for more info)
+
+error[E0599]: `u32` has no representation in SQL
+ --> tests/compile-fail/u32.rs:5:1
+  |
+5 | #[pg_extern]
+  | ^^^^^^^^^^^^ non-SQL type
+  |
+  = note: the following trait bounds were not satisfied:
+          `u32: SqlTranslatable`
+          which is required by `&u32: SqlTranslatable`
+  = note: this error originates in the attribute macro `pg_extern` (in Nightly builds, run with -Z macro-backtrace for more info)
+
+error[E0277]: the trait bound `u32: RetAbi` is not satisfied
+ --> tests/compile-fail/u32.rs:6:28
+  |
+6 | pub fn whatever(a: u32) -> u32 {
+  |                            ^^^ the trait `BoxRet` is not implemented for `u32`
+  |
+  = help: the following other types implement trait `BoxRet`:
+            f32
+            f64
+            i16
+            i32
+            i64
+            i8
+  = note: required for `u32` to implement `RetAbi`
+
+error[E0277]: `u32` cannot be passed into a Postgres function as a Datum
+ --> tests/compile-fail/u32.rs:6:17
+  |
+5 | #[pg_extern]
+  | ------------ in this procedural macro expansion
+6 | pub fn whatever(a: u32) -> u32 {
+  |                 ^ the trait `ArgAbi<'_>` is not implemented for `u32`
+  |
+  = help: the following other types implement trait `ArgAbi<'fcx>`:
+            f32
+            f64
+            i16
+            i32
+            i64
+            i8
+note: required by a bound in `pgrx::callconv::Args::<'a, 'fcx>::next_arg_unchecked`
+ --> $WORKSPACE/pgrx/src/callconv.rs
+  |
+  |     pub unsafe fn next_arg_unchecked<T: ArgAbi<'fcx>>(&mut self) -> Option<T> {
+  |                                         ^^^^^^^^^^^^ required by this bound in `Args::<'a, 'fcx>::next_arg_unchecked`
+  = note: this error originates in the attribute macro `pg_extern` (in Nightly builds, run with -Z macro-backtrace for more info)
+
+error[E0277]: the trait bound `u32: RetAbi` is not satisfied
+ --> tests/compile-fail/u32.rs:6:32
+  |
+5 |   #[pg_extern]
+  |   ------------ in this procedural macro expansion
+6 |   pub fn whatever(a: u32) -> u32 {
+  |  ________________________________^
+7 | |     a
+8 | | }
+  | |_^ the trait `BoxRet` is not implemented for `u32`
+  |
+  = help: the following other types implement trait `BoxRet`:
+            f32
+            f64
+            i16
+            i32
+            i64
+            i8
+  = note: required for `u32` to implement `RetAbi`
+  = note: this error originates in the attribute macro `pg_extern` (in Nightly builds, run with -Z macro-backtrace for more info)

pgrx-tests/tests/todo/busted-exotic-signature.stderr

@@ -1,4 +1,4 @@
-error[E0277]: the trait bound `Vec<Option<PgHeapTuple<'_, AllocatedByRust>>>: ArgAbi<'_>` is not satisfied
+error[E0277]: `Vec<Option<PgHeapTuple<'_, AllocatedByRust>>>` cannot be passed into a Postgres function as a Datum
   --> tests/todo/busted-exotic-signature.rs:12:9
    |
 10 |     #[pg_extern]

pgrx-tests/tests/todo/composite-types-broken-on-spi.stderr

@@ -1,4 +1,4 @@
-error[E0277]: the trait bound `Vec<Option<pgrx::prelude::PgHeapTuple<'_, pgrx::AllocatedByRust>>>: ArgAbi<'_>` is not satisfied
+error[E0277]: `Vec<Option<pgrx::prelude::PgHeapTuple<'_, pgrx::AllocatedByRust>>>` cannot be passed into a Postgres function as a Datum
   --> tests/todo/composite-types-broken-on-spi.rs:60:9
    |
 58 |     #[pg_extern]
@@ -18,7 +18,7 @@ note: required by a bound in `pgrx::callconv::Args::<'a, 'fcx>::next_arg_uncheck
    |                                         ^^^^^^^^^^^^ required by this bound in `Args::<'a, 'fcx>::next_arg_unchecked`
    = note: this error originates in the attribute macro `pg_extern` (in Nightly builds, run with -Z macro-backtrace for more info)
 
-error[E0277]: the trait bound `Vec<Option<pgrx::prelude::PgHeapTuple<'_, pgrx::AllocatedByRust>>>: ArgAbi<'_>` is not satisfied
+error[E0277]: `Vec<Option<pgrx::prelude::PgHeapTuple<'_, pgrx::AllocatedByRust>>>` cannot be passed into a Postgres function as a Datum
   --> tests/todo/composite-types-broken-on-spi.rs:77:9
    |
 75 |     #[pg_extern]
@@ -38,7 +38,7 @@ note: required by a bound in `pgrx::callconv::Args::<'a, 'fcx>::next_arg_uncheck
    |                                         ^^^^^^^^^^^^ required by this bound in `Args::<'a, 'fcx>::next_arg_unchecked`
    = note: this error originates in the attribute macro `pg_extern` (in Nightly builds, run with -Z macro-backtrace for more info)
 
-error[E0277]: the trait bound `Vec<Option<pgrx::prelude::PgHeapTuple<'_, pgrx::AllocatedByRust>>>: ArgAbi<'_>` is not satisfied
+error[E0277]: `Vec<Option<pgrx::prelude::PgHeapTuple<'_, pgrx::AllocatedByRust>>>` cannot be passed into a Postgres function as a Datum
   --> tests/todo/composite-types-broken-on-spi.rs:97:9
    |
 95 |     #[pg_extern]

pgrx-tests/tests/todo/random-vec-strs-arent-okay.stderr

@@ -1,4 +1,4 @@
-error[E0277]: the trait bound `Vec<Option<&str>>: ArgAbi<'_>` is not satisfied
+error[E0277]: `Vec<Option<&str>>` cannot be passed into a Postgres function as a Datum
  --> tests/todo/random-vec-strs-arent-okay.rs:8:5
   |
 5 | #[pg_extern]

pgrx-tests/tests/todo/roundtrip-tests.stderr

@@ -55,7 +55,7 @@ help: consider introducing lifetime `'a` here
 68 |         test_rt_array_refstr<'a>,
    |                             ++++
 
-error[E0277]: the trait bound `Vec<Option<&[u8]>>: ArgAbi<'_>` is not satisfied
+error[E0277]: `Vec<Option<&[u8]>>` cannot be passed into a Postgres function as a Datum
   --> tests/todo/roundtrip-tests.rs:22:23
    |
 22 |               fn $fname(i: $rtype) -> $rtype {
@@ -138,7 +138,7 @@ note: required by a bound in `pgrx::Spi::get_one_with_args`
    |                                       ^^^^^^^^^ required by this bound in `Spi::get_one_with_args`
    = note: this error originates in the macro `roundtrip_test` which comes from the expansion of the macro `roundtrip` (in Nightly builds, run with -Z macro-backtrace for more info)
 
-error[E0277]: the trait bound `Vec<Option<&CStr>>: ArgAbi<'_>` is not satisfied
+error[E0277]: `Vec<Option<&CStr>>` cannot be passed into a Postgres function as a Datum
   --> tests/todo/roundtrip-tests.rs:22:23
    |
 22 |               fn $fname(i: $rtype) -> $rtype {

pgrx-tests/tests/todo/vec-option-composite_type-nesting-problems.stderr

@@ -1,4 +1,4 @@
-error[E0277]: the trait bound `Vec<Option<pgrx::prelude::PgHeapTuple<'_, pgrx::AllocatedByRust>>>: ArgAbi<'_>` is not satisfied
+error[E0277]: `Vec<Option<pgrx::prelude::PgHeapTuple<'_, pgrx::AllocatedByRust>>>` cannot be passed into a Postgres function as a Datum
   --> tests/todo/vec-option-composite_type-nesting-problems.rs:55:5
    |
 53 | #[pg_extern]
@@ -18,7 +18,7 @@ note: required by a bound in `pgrx::callconv::Args::<'a, 'fcx>::next_arg_uncheck
    |                                         ^^^^^^^^^^^^ required by this bound in `Args::<'a, 'fcx>::next_arg_unchecked`
    = note: this error originates in the attribute macro `pg_extern` (in Nightly builds, run with -Z macro-backtrace for more info)
 
-error[E0277]: the trait bound `Vec<Option<pgrx::prelude::PgHeapTuple<'_, pgrx::AllocatedByRust>>>: ArgAbi<'_>` is not satisfied
+error[E0277]: `Vec<Option<pgrx::prelude::PgHeapTuple<'_, pgrx::AllocatedByRust>>>` cannot be passed into a Postgres function as a Datum
   --> tests/todo/vec-option-composite_type-nesting-problems.rs:72:5
    |
 70 | #[pg_extern]
@@ -38,7 +38,7 @@ note: required by a bound in `pgrx::callconv::Args::<'a, 'fcx>::next_arg_uncheck
    |                                         ^^^^^^^^^^^^ required by this bound in `Args::<'a, 'fcx>::next_arg_unchecked`
    = note: this error originates in the attribute macro `pg_extern` (in Nightly builds, run with -Z macro-backtrace for more info)
 
-error[E0277]: the trait bound `Vec<Option<pgrx::prelude::PgHeapTuple<'_, pgrx::AllocatedByRust>>>: ArgAbi<'_>` is not satisfied
+error[E0277]: `Vec<Option<pgrx::prelude::PgHeapTuple<'_, pgrx::AllocatedByRust>>>` cannot be passed into a Postgres function as a Datum
   --> tests/todo/vec-option-composite_type-nesting-problems.rs:89:5
    |
 87 | #[pg_extern]

pgrx/src/callconv.rs

@@ -60,6 +60,9 @@ static VIRTUAL_ARGUMENT: ReadOnly<pg_sys::NullableDatum> =
 /// This trait is exposed to external code so macro-generated wrapper fn may expand to calls to it.
 /// The number of invariants implementers must uphold is unlikely to be adequately documented.
 /// Prefer to use ArgAbi as a trait bound instead of implementing it, or even calling it, yourself.
+#[diagnostic::on_unimplemented(
+    message = "`{Self}` cannot be passed into a Postgres function as a Datum"
+)]
 pub unsafe trait ArgAbi<'fcx>: Sized {
     /// Unbox an argument with a matching type.
     ///
@@ -378,6 +381,10 @@ pub unsafe trait RetAbi: Sized {
 /// Postgres functions, pgrx uses a very complicated trait, RetAbi. In practice, however, most
 /// types do not need to think about its many sharp-edged cases. Instead, they should implement
 /// this simplified trait, BoxRet. A blanket impl of RetAbi for BoxRet takes care of the rest.
+#[diagnostic::on_unimplemented(
+    message = "{Self} cannot be returned from a Postgres function as a Datum",
+    note = "implement BoxRet instead if possible"
+)]
 pub unsafe trait BoxRet: Sized {
     /// # Safety
     /// You have to actually return the resulting Datum to the function.