Merge remote-tracking branch 'origin/master' into kim/reset-database

Author: kim

.github/workflows/docs-check-links.yml

@@ -0,0 +1,56 @@
+name: Docs / Publish
+
+permissions:
+  contents: read
+
+on:
+  push:
+    branches:
+      - docs/release
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '22'
+      
+      - uses: pnpm/action-setup@v4
+        with:
+          run_install: true
+
+      - name: Get pnpm store directory
+        working-directory: sdks/typescript
+        shell: bash
+        run: |
+          echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV
+
+      - uses: actions/cache@v4
+        name: Setup pnpm cache
+        with:
+          path: ${{ env.STORE_PATH }}
+          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-pnpm-store-
+
+      - name: Install dependencies
+        working-directory: docs
+        run: pnpm install
+
+      - name: Docusaurus build
+        working-directory: docs
+        run: pnpm build
+
+      - name: Publish docs to S3
+        uses: shallwefootball/s3-upload-action@master
+        with:
+          aws_key_id: ${{ secrets.DOCS_AWS_KEY_ID }}
+          aws_secret_access_key: ${{ secrets.DOCS_AWS_SECRET_ACCESS_KEY}}
+          aws_bucket: spacetimedb-docs
+          source_dir: docs/build
+          destination_dir: 'docs'

.github/workflows/docs-publish.yaml

@@ -0,0 +1,44 @@
+name: Docs / Test
+permissions:
+  contents: read
+
+on:
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '22'
+      
+      - uses: pnpm/action-setup@v4
+        with:
+          run_install: true
+
+      - name: Get pnpm store directory
+        working-directory: sdks/typescript
+        shell: bash
+        run: |
+          echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV
+
+      - uses: actions/cache@v4
+        name: Setup pnpm cache
+        with:
+          path: ${{ env.STORE_PATH }}
+          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-pnpm-store-
+
+      - name: Install dependencies
+        working-directory: docs
+        run: pnpm install
+
+      - name: Docusaurus build
+        working-directory: docs
+        run: pnpm build

.github/workflows/docs-test.yaml

@@ -8,6 +8,7 @@
 //
 // (private documentation for the macro authors is totally fine here and you SHOULD write that!)
 
+mod procedure;
 mod reducer;
 mod sats;
 mod table;
@@ -105,6 +106,14 @@ mod sym {
     }
 }
 
+#[proc_macro_attribute]
+pub fn procedure(args: StdTokenStream, item: StdTokenStream) -> StdTokenStream {
+    cvt_attr::<ItemFn>(args, item, quote!(), |args, original_function| {
+        let args = procedure::ProcedureArgs::parse(args)?;
+        procedure::procedure_impl(args, original_function)
+    })
+}
+
 #[proc_macro_attribute]
 pub fn reducer(args: StdTokenStream, item: StdTokenStream) -> StdTokenStream {
     cvt_attr::<ItemFn>(args, item, quote!(), |args, original_function| {
@@ -116,7 +125,7 @@ pub fn reducer(args: StdTokenStream, item: StdTokenStream) -> StdTokenStream {
 #[proc_macro_attribute]
 pub fn view(args: StdTokenStream, item: StdTokenStream) -> StdTokenStream {
     cvt_attr::<ItemFn>(args, item, quote!(), |args, original_function| {
-        let args = view::ViewArgs::parse(args)?;
+        let args = view::ViewArgs::parse(args, &original_function.sig.ident)?;
         view::view_impl(args, original_function)
     })
 }

.github/workflows/docs-validate-nav-build.yml

@@ -0,0 +1,130 @@
+use crate::reducer::{assert_only_lifetime_generics, extract_typed_args};
+use crate::sym;
+use crate::util::{check_duplicate, ident_to_litstr, match_meta};
+use proc_macro2::TokenStream;
+use quote::quote;
+use syn::parse::Parser as _;
+use syn::{ItemFn, LitStr};
+
+#[derive(Default)]
+pub(crate) struct ProcedureArgs {
+    /// For consistency with reducers: allow specifying a different export name than the Rust function name.
+    name: Option<LitStr>,
+}
+
+impl ProcedureArgs {
+    pub(crate) fn parse(input: TokenStream) -> syn::Result<Self> {
+        let mut args = Self::default();
+        syn::meta::parser(|meta| {
+            match_meta!(match meta {
+                sym::name => {
+                    check_duplicate(&args.name, &meta)?;
+                    args.name = Some(meta.value()?.parse()?);
+                }
+            });
+            Ok(())
+        })
+        .parse2(input)?;
+        Ok(args)
+    }
+}
+
+pub(crate) fn procedure_impl(args: ProcedureArgs, original_function: &ItemFn) -> syn::Result<TokenStream> {
+    let func_name = &original_function.sig.ident;
+    let vis = &original_function.vis;
+
+    let procedure_name = args.name.unwrap_or_else(|| ident_to_litstr(func_name));
+
+    assert_only_lifetime_generics(original_function, "procedures")?;
+
+    let typed_args = extract_typed_args(original_function)?;
+
+    // TODO: Require that procedures be `async` functions syntactically,
+    // and use `futures_util::FutureExt::now_or_never` to poll them.
+    // if !&original_function.sig.asyncness.is_some() {
+    //     return Err(syn::Error::new_spanned(
+    //         original_function.sig.clone(),
+    //         "procedures must be `async`",
+    //     ));
+    // };
+
+    // Extract all function parameter names.
+    let opt_arg_names = typed_args.iter().map(|arg| {
+        if let syn::Pat::Ident(i) = &*arg.pat {
+            let name = i.ident.to_string();
+            quote!(Some(#name))
+        } else {
+            quote!(None)
+        }
+    });
+
+    let arg_tys = typed_args.iter().map(|arg| arg.ty.as_ref()).collect::<Vec<_>>();
+    let first_arg_ty = arg_tys.first().into_iter();
+    let rest_arg_tys = arg_tys.iter().skip(1);
+
+    // Extract the return type.
+    let ret_ty_for_assert = match &original_function.sig.output {
+        syn::ReturnType::Default => None,
+        syn::ReturnType::Type(_, t) => Some(&**t),
+    }
+    .into_iter();
+
+    let ret_ty_for_info = match &original_function.sig.output {
+        syn::ReturnType::Default => quote!(()),
+        syn::ReturnType::Type(_, t) => quote!(#t),
+    };
+
+    let register_describer_symbol = format!("__preinit__20_register_describer_{}", procedure_name.value());
+
+    let lifetime_params = &original_function.sig.generics;
+    let lifetime_where_clause = &lifetime_params.where_clause;
+
+    let generated_describe_function = quote! {
+        #[export_name = #register_describer_symbol]
+        pub extern "C" fn __register_describer() {
+            spacetimedb::rt::register_procedure::<_, _, #func_name>(#func_name)
+        }
+    };
+
+    Ok(quote! {
+        const _: () = {
+            #generated_describe_function
+        };
+        #[allow(non_camel_case_types)]
+        #vis struct #func_name { _never: ::core::convert::Infallible }
+        const _: () = {
+            fn _assert_args #lifetime_params () #lifetime_where_clause {
+                #(let _ = <#first_arg_ty as spacetimedb::rt::ProcedureContextArg>::_ITEM;)*
+                #(let _ = <#rest_arg_tys as spacetimedb::rt::ProcedureArg>::_ITEM;)*
+                #(let _ = <#ret_ty_for_assert as spacetimedb::rt::IntoProcedureResult>::to_result;)*
+            }
+        };
+        impl #func_name {
+            fn invoke(__ctx: spacetimedb::ProcedureContext, __args: &[u8]) -> spacetimedb::ProcedureResult {
+                spacetimedb::rt::invoke_procedure(#func_name, __ctx, __args)
+            }
+        }
+        #[automatically_derived]
+        impl spacetimedb::rt::FnInfo for #func_name {
+            /// The type of this function.
+            type Invoke = spacetimedb::rt::ProcedureFn;
+
+            /// The function kind, which will cause scheduled tables to accept procedures.
+            type FnKind = spacetimedb::rt::FnKindProcedure<#ret_ty_for_info>;
+
+            /// The name of this function
+            const NAME: &'static str = #procedure_name;
+
+            /// The parameter names of this function
+            const ARG_NAMES: &'static [Option<&'static str>] = &[#(#opt_arg_names),*];
+
+            /// The pointer for invoking this function
+            const INVOKE: spacetimedb::rt::ProcedureFn = #func_name::invoke;
+
+            /// The return type of this function
+            fn return_type(ts: &mut impl spacetimedb::sats::typespace::TypespaceBuilder) -> Option<spacetimedb::sats::AlgebraicType> {
+                Some(<#ret_ty_for_info as spacetimedb::SpacetimeType>::make_type(ts))
+            }
+        }
+    })
+}