Struct CommitBuilder

pub struct CommitBuilder<'a, T> { /* private fields */ }

The CommitBuilder is used to easily and dynamically build commit messages. It operates in a series of stages:

The Initial stage is used to populate the builder with proposals and other data using method calls on the builder that let the builder stay in the same stage.

The next stage is LoadedPsks, and it signifies the stage after the builder loaded the the pre-shared keys for the PreSharedKey proposals in this commit.

Then comes the Complete stage, which denotes that all data has been validated. From this stage, the commit can be staged in the group, and the outgoing messages returned.

For example, to create a commit to a new Add proposal with a KeyPackage key_package_to_add that does not commit to the proposals in the proposal store, one could build the commit as follows:

let message_bundle: CommitMessageBundle = mls_group
  .commit_builder()
  .consume_proposal_store(false)
  .add_proposal(key_package_to_add)
  .load_psks(provider.storage())?
  .build(provider.rand(), provider.crypto(), signer, app_policy_proposals)?
  .stage_commit(provider)?;

let commit = message_bundle.commit();
let welcome = message_bundle.welcome().expect("expected a welcome since there was an add");
let group_info = message_bundle.welcome().expect("expected a group info since there was an add");

In this example signer is a reference to a [Signer] and app_policy_proposals is the application-defined policy for which proposals to accept, implemented by an FnMut(&QueuedProposal) -> bool.

See the book for another example.

Implementations

impl<'a> CommitBuilder<'a, Initial>

pub fn new(group: &'a mut MlsGroup) -> Self

returns a new CommitBuilder for the given MlsGroup.

pub fn consume_proposal_store(self, consume_proposal_store: bool) -> Self

Sets whether or not the proposals in the proposal store of the group should be included in the commit. Defaults to true.

pub fn create_group_info(self, create_group_info: bool) -> Self

Sets whether or not a GroupInfo should be created when the commit is staged. Defaults to the value of the MlsGroups MlsGroupJoinConfig.

pub fn force_self_update(self, force_self_update: bool) -> Self

Sets whether or not the commit should force a self-update. Defaults to false.

pub fn add_proposal(self, proposal: Proposal) -> Self

Adds a proposal to the proposals to be committed.

pub fn add_proposals( self, proposals: impl IntoIterator<Item = Proposal>, ) -> Self

Adds the proposals in the iterator to the proposals to be committed.

pub fn leaf_node_parameters( self, leaf_node_parameters: LeafNodeParameters, ) -> Self

Sets the leaf node parameters for the new leaf node in a self-update. Implies that a self-update takes place.

pub fn propose_adds( self, key_packages: impl IntoIterator<Item = KeyPackage>, ) -> Self

Adds an Add proposal to the provided KeyPackage to the list of proposals to be committed.

pub fn propose_removals( self, removed: impl IntoIterator<Item = LeafNodeIndex>, ) -> Self

Adds a Remove proposal for the provided LeafNodeIndexes to the list of proposals to be committed.

pub fn propose_group_context_extensions(self, extensions: Extensions) -> Self

Adds a GroupContextExtensions proposal for the provided Extensions to the list of proposals to be committed.

pub fn load_psks<Storage: StorageProvider>( self, storage: &'a Storage, ) -> Result<CommitBuilder<'a, LoadedPsks>, CreateCommitError>

Loads the PSKs for the PskProposals marked for inclusion and moves on to the next phase.

impl<'a> CommitBuilder<'a, LoadedPsks>

pub fn build<S: Signer>( self, rand: &impl OpenMlsRand, crypto: &impl OpenMlsCrypto, signer: &S, f: impl FnMut(&QueuedProposal) -> bool, ) -> Result<CommitBuilder<'a, Complete>, CreateCommitError>

Validates the inputs and builds the commit. The last argument f is a function that lets the caller filter the proposals that are considered for inclusion. This provides a way for the application to enforce custom policies in the creation of commits.

pub fn build_with_new_signer<S: Signer>( self, rand: &impl OpenMlsRand, crypto: &impl OpenMlsCrypto, old_signer: &impl Signer, new_signer: NewSignerBundle<'_, S>, f: impl FnMut(&QueuedProposal) -> bool, ) -> Result<CommitBuilder<'a, Complete>, CreateCommitError>

Just like build, this function validates the inputs and builds the commit. The last argument f is a function that lets the caller filter the proposals that are considered for inclusion. This provides a way for the application to enforce custom policies in the creation of commits.

In contrast to build, this function can be used to create commits that rotate the own leaf node’s signature key.

impl CommitBuilder<'_, Complete>

pub fn stage_commit<Provider: OpenMlsProvider>( self, provider: &Provider, ) -> Result<CommitMessageBundle, CommitBuilderStageError<Provider::StorageError>>

Stages the commit and returns the protocol messages.

Trait Implementations

impl<'a, T: Debug> Debug for CommitBuilder<'a, T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.