with_options/
lib.rs

1// Copyright 2025 RisingWave Labs
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15use proc_macro::TokenStream;
16use quote::quote;
17use syn::{DeriveInput, parse_macro_input};
18
19/// Annotates that the struct represents the `WITH` properties for a connector.
20/// This implements a marker trait `WithOptions`.
21/// It's also used to generate the `with_option_*.yaml` files.
22///
23/// ## Notes about how to define property structs
24///
25/// ### Prefer strongly-typed fields
26///
27/// Avoid using `HashMap` with `#[serde(flatten)]` to include all unknown fields.
28/// Declare all fields explicitly instead.
29///
30/// The only exception now is CDC, which needs to pass a lot of options as-is to Debezium.
31///
32/// ### Common struct
33///
34/// When there are some fields can be grouped together, and/or can be shared by source and sink,
35/// or by multiple connectors, define a struct for them and use the common struct as a
36/// `#[serde(flatten)]` field.
37///
38/// Add `#[derive(WithOptions)]` to both the outer and the inner struct.
39///
40/// Avoid using nested `#[serde(flatten)]` field in the common struct,
41/// because this will lead to unexpected serde behaviors.
42/// Put all flatten fields in the top-level struct instead.
43#[proc_macro_derive(WithOptions, attributes(with_option))]
44pub fn derive_helper_attr(input: TokenStream) -> TokenStream {
45    let input = parse_macro_input!(input as DeriveInput);
46
47    let fields = match input.data {
48        syn::Data::Struct(ref data) => match data.fields {
49            syn::Fields::Named(ref fields) => &fields.named,
50            _ => return quote! { compile_error!("WithOptions can only be derived for structs with named fields"); }.into(),
51        },
52        _ => return quote! { compile_error!("WithOptions can only be derived for structs"); }.into(),
53    };
54
55    let mut assert_impls = vec![];
56
57    for field in fields {
58        let field_name = field.ident.as_ref().unwrap();
59
60        assert_impls.push(quote!(
61            crate::with_options::WithOptions::assert_receiver_is_with_options(&self.#field_name);
62        ))
63    }
64
65    let struct_name = input.ident;
66    // This macro is only be expected to used in risingwave_connector. This trait is also defined there.
67    if input.generics.params.is_empty() {
68        quote! {
69            impl crate::with_options::WithOptions for #struct_name {
70                fn assert_receiver_is_with_options(&self) {
71                    #(#assert_impls)*
72                }
73            }
74        }
75        .into()
76    } else {
77        // Note: CDC properties have generics.
78        let (impl_generics, ty_generics, where_clause) = input.generics.split_for_impl();
79        quote! {
80            impl #impl_generics crate::with_options::WithOptions for #struct_name #ty_generics #where_clause {
81                fn assert_receiver_is_with_options(&self) {
82                    #(#assert_impls)*
83                }
84            }
85        }.into()
86    }
87}
with_options/lib.rs

with_options/
lib.rs
