Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,11 @@ cargo clippy --workspace --tests
cargo run -p codegen
```

The `State` and `Resource` messages are written by hand in
`sdk/src/proto/state.rs` so that they keep unknown fields. When an update of
the vendored proto changes either message, update that file to match; a test
fails until you do.

## Submitting changes

* Open an issue first for anything beyond a small fix, so we can agree on the
Expand Down
5 changes: 3 additions & 2 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

6 changes: 6 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -102,6 +102,12 @@ with a few deliberate differences:
`Server::ready`: until it completes, the server reports NOT_SERVING and
answers RunFunction with UNAVAILABLE, and if it fails, the server stops
with `Error::NotReady`.
- **Unknown fields are kept on `State` and `Resource` only.** protobuf-go
keeps fields it does not know on every message. This SDK keeps them on the
two messages `response::to` copies from the request, so a field a newer
Crossplane adds to them passes through a function unchanged.
As in Go, replacing a desired resource instead of modifying it in place
drops that resource's unknown fields.
- **Graceful shutdown is built in.** The server drains in-flight requests on
SIGTERM and SIGINT.
- **Metrics are Go-compatible, served as OpenMetrics first.** Like
Expand Down
74 changes: 73 additions & 1 deletion codegen/src/main.rs
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,11 @@ const PROTO: &str = "sdk/proto/v1/run_function.proto";
const INCLUDE: &str = "sdk/proto";
const OUT: &str = "sdk/src/generated";

/// Messages written by hand in `sdk/src/proto/state.rs` so that they keep
/// unknown fields, which prost-generated messages discard.
const HAND_WRITTEN: [&str; 2] = ["State", "Resource"];
const UNKNOWN_FIELDS_INIT: &str = "unknown_fields: Default::default(),";

fn main() -> Result<(), Box<dyn Error>> {
let root = workspace_root();
let tmp = tempfile::tempdir()?;
Expand All @@ -21,6 +26,12 @@ fn main() -> Result<(), Box<dyn Error>> {
.file_descriptor_set_path(&descriptor)
.compile_well_known_types()
.extern_path(".google.protobuf", "::pbjson_types");
for message in HAND_WRITTEN {
config.extern_path(
format!(".apiextensions.fn.proto.v1.{message}"),
format!("crate::proto::state::{message}"),
);
}

tonic_prost_build::configure()
.build_client(true)
Expand Down Expand Up @@ -49,17 +60,78 @@ fn main() -> Result<(), Box<dyn Error>> {
} else {
continue;
};
fs::copy(&path, out.join(target))?;
if target == "v1.serde.rs" {
let serde = init_unknown_fields(&fs::read_to_string(&path)?)?;
fs::write(out.join(target), serde)?;
} else {
fs::copy(&path, out.join(target))?;
}
println!("wrote {}", out.join(target).display());
}
fs::copy(&descriptor, out.join("fileset.bin"))?;
println!("wrote {}", out.join("fileset.bin").display());
Ok(())
}

/// Makes the generated serde constructors of the hand-written messages
/// initialize `unknown_fields`, a field the descriptor does not have.
fn init_unknown_fields(serde: &str) -> Result<String, Box<dyn Error>> {
let mut patched = serde.to_owned();
for message in HAND_WRITTEN {
let constructor = format!("Ok({message} {{\n");
if patched.matches(&constructor).count() != 1 {
return Err(format!("expected one serde constructor for {message}").into());
}
let start = patched.find(&constructor).expect("counted above");
let end = start
+ patched[start..]
.find("})")
.ok_or_else(|| format!("unterminated serde constructor for {message}"))?;
let line_start = patched[..end].rfind('\n').map_or(0, |i| i + 1);
let indent = &patched[line_start..end];
let init = format!("{indent} {UNKNOWN_FIELDS_INIT}\n");
patched.insert_str(line_start, &init);
}
Ok(patched)
}

fn workspace_root() -> PathBuf {
PathBuf::from(env!("CARGO_MANIFEST_DIR"))
.parent()
.expect("codegen crate lives one level below the workspace root")
.to_path_buf()
}

#[cfg(test)]
mod tests {
use super::*;

const GENERATED: &str = "\
Ok(Resource {
ready: ready__.unwrap_or_default(),
})
Ok(State {
composite: composite__,
})
";

#[test]
fn init_unknown_fields_extends_both_constructors() {
let want = "\
Ok(Resource {
ready: ready__.unwrap_or_default(),
unknown_fields: Default::default(),
})
Ok(State {
composite: composite__,
unknown_fields: Default::default(),
})
";
assert_eq!(init_unknown_fields(GENERATED).expect("patches"), want);
}

#[test]
fn init_unknown_fields_fails_without_a_constructor() {
assert!(init_unknown_fields("Ok(State {\n})").is_err());
}
}
1 change: 1 addition & 0 deletions sdk/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -35,4 +35,5 @@ thiserror = "2"
rustls = { version = "0.23.45", default-features = false }

[dev-dependencies]
prost-types = "0.14"
tokio-test = "0.4"
77 changes: 4 additions & 73 deletions sdk/src/generated/v1.rs
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ pub struct RunFunctionRequest {
/// to each function is fresh as of the time the pipeline was invoked, not as
/// of the time each function was invoked.
#[prost(message, optional, tag = "2")]
pub observed: ::core::option::Option<State>,
pub observed: ::core::option::Option<crate::proto::state::State>,
/// Desired state according to a function pipeline. The state passed to a
/// particular function may have been accumulated by previous functions in the
/// pipeline.
Expand All @@ -22,7 +22,7 @@ pub struct RunFunctionRequest {
/// as desired before will result in them being deleted from the objects in the
/// cluster.
#[prost(message, optional, tag = "3")]
pub desired: ::core::option::Option<State>,
pub desired: ::core::option::Option<crate::proto::state::State>,
/// Optional input specific to this function invocation. A JSON representation
/// of the 'input' block of the relevant entry in a function pipeline.
#[prost(message, optional, tag = "4")]
Expand Down Expand Up @@ -111,7 +111,7 @@ pub struct CredentialData {
#[derive(Clone, PartialEq, ::prost::Message)]
pub struct Resources {
#[prost(message, repeated, tag = "1")]
pub items: ::prost::alloc::vec::Vec<Resource>,
pub items: ::prost::alloc::vec::Vec<crate::proto::state::Resource>,
}
/// A RunFunctionResponse contains the result of a function run.
#[allow(clippy::all)]
Expand All @@ -132,7 +132,7 @@ pub struct RunFunctionResponse {
/// as desired before will result in them being deleted from the objects in the
/// cluster.
#[prost(message, optional, tag = "2")]
pub desired: ::core::option::Option<State>,
pub desired: ::core::option::Option<crate::proto::state::State>,
/// Results of the function run. Results are used for observability purposes.
#[prost(message, repeated, tag = "3")]
pub results: ::prost::alloc::vec::Vec<Result>,
Expand Down Expand Up @@ -275,75 +275,6 @@ pub struct ResponseMeta {
#[prost(message, optional, tag = "2")]
pub ttl: ::core::option::Option<::pbjson_types::Duration>,
}
/// State of the XR (XR) and any resources.
#[allow(clippy::all)]
#[derive(Clone, PartialEq, ::prost::Message)]
pub struct State {
/// The state of the XR (XR).
#[prost(message, optional, tag = "1")]
pub composite: ::core::option::Option<Resource>,
/// The state of any other resources. In composition functions these are the
/// composed resources. In operation functions they're arbitrary resources that
/// the operation wants to create or update.
#[prost(map = "string, message", tag = "2")]
pub resources: ::std::collections::HashMap<::prost::alloc::string::String, Resource>,
}
/// A Resource represents the state of a Kubernetes resource.
#[allow(clippy::all)]
#[derive(Clone, PartialEq, ::prost::Message)]
pub struct Resource {
/// The JSON representation of the resource.
///
/// * Crossplane will set this field in a RunFunctionRequest to the entire
/// observed state of a resource - including its metadata, spec, and status.
///
/// * A function should set this field in a RunFunctionRequest to communicate
/// the desired state of the resource.
///
/// * A function may only specify the desired status of a XR - not its metadata
/// or spec. A function should not return desired metadata or spec for a XR.
/// This will be ignored.
///
/// * A function may not specify the desired status of any other resource -
/// e.g. composed resources. It may only specify their metadata and spec.
/// Status will be ignored.
#[prost(message, optional, tag = "1")]
pub resource: ::core::option::Option<::pbjson_types::Struct>,
/// The resource's connection details.
///
/// * Crossplane will set this field in a RunFunctionRequest to communicate the
/// the observed connection details of a composite or composed resource.
///
/// * A function should set this field in a RunFunctionResponse to indicate the
/// desired connection details of legacy XRs. For modern XRs, this will be ignored.
///
/// * A function should not set this field in a RunFunctionResponse to indicate
/// the desired connection details of a composed resource. This will be
/// ignored.
///
/// Connection details are only used for composition. They're ignored by
/// Operations.
#[prost(map = "string, bytes", tag = "2")]
pub connection_details: ::std::collections::HashMap<
::prost::alloc::string::String,
::prost::alloc::vec::Vec<u8>,
>,
/// Ready indicates whether the resource should be considered ready.
///
/// * Crossplane will never set this field in a RunFunctionRequest.
///
/// * A function should set this field to READY_TRUE in a RunFunctionResponse
/// to indicate that a desired resource is ready.
///
/// * A function should set this field to READY_TRUE in a RunFunctionResponse
/// to indicate that a desired XR is ready. This overwrites the standard
/// readiness detection that determines the ready state of the composite by the
/// ready state of the composed resources.
///
/// Ready is only used for composition. It's ignored by Operations.
#[prost(enumeration = "Ready", tag = "3")]
pub ready: i32,
}
/// A Result of running a function.
#[allow(clippy::all)]
#[derive(Clone, PartialEq, Eq, Hash, ::prost::Message)]
Expand Down
2 changes: 2 additions & 0 deletions sdk/src/generated/v1.serde.rs
Original file line number Diff line number Diff line change
Expand Up @@ -975,6 +975,7 @@ impl<'de> serde::Deserialize<'de> for Resource {
resource: resource__,
connection_details: connection_details__.unwrap_or_default(),
ready: ready__.unwrap_or_default(),
unknown_fields: Default::default(),
})
}
}
Expand Down Expand Up @@ -2301,6 +2302,7 @@ impl<'de> serde::Deserialize<'de> for State {
Ok(State {
composite: composite__,
resources: resources__.unwrap_or_default(),
unknown_fields: Default::default(),
})
}
}
Expand Down
7 changes: 7 additions & 0 deletions sdk/src/proto.rs
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,17 @@
//! `apiextensions.fn.proto.v1` FunctionRunnerService API.
//!
//! Regenerate with `cargo run -p codegen` after changing the vendored proto.
//! `State` and `Resource` are written by hand in `proto/state.rs` to keep
//! unknown fields; update them when the proto changes either message.

mod state;

pub use state::UnknownFields;

/// Types and the gRPC service for the v1 FunctionRunnerService API.
pub mod v1 {
#![allow(clippy::all, clippy::pedantic)]
pub use super::state::{Resource, State};
include!("generated/v1.rs");
include!("generated/v1.serde.rs");
}
Expand Down
Loading
Loading