Struct holochain_types::dna::DnaFile

pub struct DnaFile { /* private fields */ }

Represents a full DNA, including DnaDef and WebAssembly bytecode.

Historical note: This struct was written before DnaBundle was introduced. This used to be our file representation of a full distributable DNA. That function has been superseded by DnaBundle, but we use this type widely, so there is simply a way to convert from DnaBundle to DnaFile.

TODO: Once we remove the InstallApp command which accepts a DnaFile, we should remove the Serialize impl on this type, and perhaps rename to indicate that this is simply a validated, fully-formed DnaBundle (i.e. all Wasms are bundled and immediately available, not remote.)

Implementations

impl DnaFile

pub async fn new(dna: DnaDef, wasm: impl IntoIterator<Item = DnaWasm>) -> Self

Construct a new DnaFile instance.

Examples found in repository

src/dna/dna_file.rs (line 208)

    pub async fn with_properties(self, properties: SerializedBytes) -> Self {
        let (mut dna, wasm): (DnaDef, Vec<wasm::DnaWasm>) = self.into();
        dna.modifiers.properties = properties;
        DnaFile::new(dna, wasm).await
    }

    /// Transform this DnaFile into a new DnaFile with a different network seed
    /// and, hence, a different DnaHash.
    pub async fn with_network_seed(self, network_seed: NetworkSeed) -> Self {
        let (mut dna, wasm): (DnaDef, Vec<wasm::DnaWasm>) = self.into();
        dna.modifiers.network_seed = network_seed;
        DnaFile::new(dna, wasm).await
    }

src/test_utils.rs (line 69)

pub fn fake_dna_zomes_named(
    network_seed: &str,
    name: &str,
    zomes: Vec<(ZomeName, DnaWasm)>,
) -> DnaFile {
    let mut dna = DnaDef {
        name: name.to_string(),
        modifiers: DnaModifiers {
            properties: YamlProperties::new(serde_yaml::from_str("p: hi").unwrap())
                .try_into()
                .unwrap(),
            network_seed: network_seed.to_string(),
            origin_time: Timestamp::HOLOCHAIN_EPOCH,
            quantum_time: kitsune_p2p_dht::spacetime::STANDARD_QUANTUM_TIME,
        },
        integrity_zomes: Vec::new(),
        coordinator_zomes: Vec::new(),
    };
    tokio_helper::block_forever_on(async move {
        let mut wasm_code = Vec::new();
        for (zome_name, wasm) in zomes {
            let wasm = crate::dna::wasm::DnaWasmHashed::from_content(wasm).await;
            let (wasm, wasm_hash) = wasm.into_inner();
            dna.integrity_zomes.push((
                zome_name,
                ZomeDef::Wasm(WasmZome {
                    wasm_hash,
                    dependencies: Default::default(),
                })
                .into(),
            ));
            wasm_code.push(wasm);
        }
        DnaFile::new(dna, wasm_code).await
    })
}

pub async fn update_coordinators(
    &mut self,
    coordinator_zomes: CoordinatorZomes,
    wasms: Vec<DnaWasm>
) -> Result<Vec<WasmHash>, DnaError>

Update coordinator zomes for this dna.

pub fn from_parts(dna: DnaDefHashed, code: WasmMap) -> Self

Construct a DnaFile from its constituent parts

Examples found in repository

src/dna/dna_bundle.rs (line 43)

    pub async fn into_dna_file(self, modifiers: DnaModifiersOpt) -> DnaResult<(DnaFile, DnaHash)> {
        let (integrity, coordinator, wasms) = self.inner_maps().await?;
        let (dna_def, original_hash) = self.to_dna_def(integrity, coordinator, modifiers)?;

        Ok((DnaFile::from_parts(dna_def, wasms), original_hash))
    }

pub fn dna(&self) -> &DnaDefHashed

The DnaDef along with its hash

pub fn dna_def(&self) -> &DnaDef

Just the DnaDef

pub fn dna_hash(&self) -> &DnaHash

The hash of the DnaDef

Examples found in repository

src/app/app_bundle.rs (line 74)

    pub async fn resolve_cells(
        self,
        agent: AgentPubKey,
        _gamut: DnaGamut,
        membrane_proofs: HashMap<RoleName, MembraneProof>,
    ) -> AppBundleResult<AppRoleResolution> {
        let AppManifestValidated { name: _, roles } = self.manifest().clone().validate()?;
        let bundle = Arc::new(self);
        let tasks = roles.into_iter().map(|(role_name, role)| async {
            let bundle = bundle.clone();
            Ok((role_name, bundle.resolve_cell(role).await?))
        });
        let resolution = futures::future::join_all(tasks)
            .await
            .into_iter()
            .collect::<AppBundleResult<Vec<_>>>()?
            .into_iter()
            .fold(
                Ok(AppRoleResolution::new(agent.clone())),
                |acc: AppBundleResult<AppRoleResolution>, (role_name, op)| {
                    if let Ok(mut resolution) = acc {
                        match op {
                            CellProvisioningOp::Create(dna, clone_limit) => {
                                let agent = resolution.agent.clone();
                                let dna_hash = dna.dna_hash().clone();
                                let cell_id = CellId::new(dna_hash, agent);
                                let role = AppRoleAssignment::new(cell_id, true, clone_limit);
                                // TODO: could sequentialize this to remove the clone
                                let proof = membrane_proofs.get(&role_name).cloned();
                                resolution.dnas_to_register.push((dna, proof));
                                resolution.role_assignments.push((role_name, role));
                            }
                            CellProvisioningOp::Existing(cell_id, clone_limit) => {
                                let role = AppRoleAssignment::new(cell_id, true, clone_limit);
                                resolution.role_assignments.push((role_name, role));
                            }
                            CellProvisioningOp::Noop(cell_id, clone_limit) => {
                                resolution.role_assignments.push((
                                    role_name,
                                    AppRoleAssignment::new(cell_id, false, clone_limit),
                                ));
                            }
                            other => {
                                tracing::error!(
                                    "Encountered unexpected CellProvisioningOp: {:?}",
                                    other
                                );
                                unimplemented!()
                            }
                        }
                        Ok(resolution)
                    } else {
                        acc
                    }
                },
            )?;

        // let resolution = cells.into_iter();
        Ok(resolution)
    }

    async fn resolve_cell(
        &self,
        role: AppRoleManifestValidated,
    ) -> AppBundleResult<CellProvisioningOp> {
        Ok(match role {
            AppRoleManifestValidated::Create {
                location,
                version,
                clone_limit,
                modifiers,
                deferred: _,
            } => {
                self.resolve_cell_create(&location, version.as_ref(), clone_limit, modifiers)
                    .await?
            }

            AppRoleManifestValidated::CreateClone { .. } => {
                unimplemented!("`create_clone` provisioning strategy is currently unimplemented")
            }
            AppRoleManifestValidated::UseExisting {
                version,
                clone_limit,
                deferred: _,
            } => self.resolve_cell_existing(&version, clone_limit),
            AppRoleManifestValidated::CreateIfNotExists {
                location,
                version,
                clone_limit,
                modifiers,
                deferred: _,
            } => match self.resolve_cell_existing(&version, clone_limit) {
                op @ CellProvisioningOp::Existing(_, _) => op,
                CellProvisioningOp::NoMatch => {
                    self.resolve_cell_create(&location, Some(&version), clone_limit, modifiers)
                        .await?
                }
                CellProvisioningOp::Conflict(_) => {
                    unimplemented!("conflicts are not handled, or even possible yet")
                }
                CellProvisioningOp::Create(_, _) => {
                    unreachable!("resolve_cell_existing will never return a Create op")
                }
                CellProvisioningOp::Noop(_, _) => {
                    unreachable!("resolve_cell_existing will never return a Noop")
                }
            },
            AppRoleManifestValidated::Disabled {
                version: _,
                clone_limit: _,
            } => {
                unimplemented!("`disabled` provisioning strategy is currently unimplemented")
                // CellProvisioningOp::Noop(clone_limit)
            }
        })
    }

    async fn resolve_cell_create(
        &self,
        location: &mr_bundle::Location,
        version: Option<&DnaVersionSpec>,
        clone_limit: u32,
        modifiers: DnaModifiersOpt,
    ) -> AppBundleResult<CellProvisioningOp> {
        let bytes = self.resolve(location).await?;
        let dna_bundle: DnaBundle = mr_bundle::Bundle::decode(&bytes)?.into();
        let (dna_file, original_dna_hash) = dna_bundle.into_dna_file(modifiers).await?;
        if let Some(spec) = version {
            if !spec.matches(original_dna_hash) {
                return Ok(CellProvisioningOp::NoMatch);
            }
        }
        Ok(CellProvisioningOp::Create(dna_file, clone_limit))
    }

    fn resolve_cell_existing(
        &self,
        _version: &DnaVersionSpec,
        _clone_limit: u32,
    ) -> CellProvisioningOp {
        unimplemented!("Reusing existing cells is not yet implemented")
    }
}

/// This function is called in places where it will be necessary to rework that
/// area after use_existing has been implemented
pub fn we_must_remember_to_rework_cell_panic_handling_after_implementing_use_existing_cell_resolution(
) {
}

/// The answer to the question:
/// "how do we concretely assign DNAs to the open roles of this App?"
/// Includes the DNAs selected to fill the roles and the details of the role assignments.
// TODO: rework, make fields private
#[allow(missing_docs)]
#[derive(PartialEq, Eq, Debug)]
pub struct AppRoleResolution {
    pub agent: AgentPubKey,
    pub dnas_to_register: Vec<(DnaFile, Option<MembraneProof>)>,
    pub role_assignments: Vec<(RoleName, AppRoleAssignment)>,
}

#[allow(missing_docs)]
impl AppRoleResolution {
    pub fn new(agent: AgentPubKey) -> Self {
        Self {
            agent,
            dnas_to_register: Default::default(),
            role_assignments: Default::default(),
        }
    }

    /// Return the IDs of new cells to be created as part of the resolution.
    /// Does not return existing cells to be reused.
    pub fn cells_to_create(&self) -> Vec<(CellId, Option<MembraneProof>)> {
        self.dnas_to_register
            .iter()
            .map(|(dna, proof)| {
                (
                    CellId::new(dna.dna_hash().clone(), self.agent.clone()),
                    proof.clone(),
                )
            })
            .collect()
    }

pub fn verify_hash(&self) -> Result<(), DnaError>

Verify that the DNA hash in the file matches the DnaDef

Examples found in repository

src/dna/dna_file.rs (line 199)

    pub async fn from_file_content(data: &[u8]) -> Result<Self, DnaError> {
        // Not super efficient memory-wise, but doesn't block any threads
        let data = data.to_vec();
        // Block because gzipping could take some time
        let dna_file = tokio::task::spawn_blocking(move || {
            let mut gz = flate2::read::GzDecoder::new(&data[..]);
            let mut bytes = Vec::new();
            use std::io::Read;
            gz.read_to_end(&mut bytes)?;
            let sb: SerializedBytes = UnsafeBytes::from(bytes).into();
            let dna_file: DnaFile = sb.try_into()?;
            DnaResult::Ok(dna_file)
        })
        .await
        .expect("blocking thread panicked - panicking here too")?;
        dna_file.verify_hash()?;
        Ok(dna_file)
    }

    /// Transform this DnaFile into a new DnaFile with different properties
    /// and, hence, a different DnaHash.
    pub async fn with_properties(self, properties: SerializedBytes) -> Self {
        let (mut dna, wasm): (DnaDef, Vec<wasm::DnaWasm>) = self.into();
        dna.modifiers.properties = properties;
        DnaFile::new(dna, wasm).await
    }

    /// Transform this DnaFile into a new DnaFile with a different network seed
    /// and, hence, a different DnaHash.
    pub async fn with_network_seed(self, network_seed: NetworkSeed) -> Self {
        let (mut dna, wasm): (DnaDef, Vec<wasm::DnaWasm>) = self.into();
        dna.modifiers.network_seed = network_seed;
        DnaFile::new(dna, wasm).await
    }

    /// The bytes of the WASM zomes referenced in the Dna portion.
    pub fn code(&self) -> &BTreeMap<holo_hash::WasmHash, wasm::DnaWasm> {
        &self.code.0
    }

    /// Fetch the Webassembly byte code for a zome.
    pub fn get_wasm_for_zome(&self, zome_name: &ZomeName) -> Result<&wasm::DnaWasm, DnaError> {
        let wasm_hash = &self.dna.get_wasm_zome(zome_name)?.wasm_hash;
        self.code.0.get(wasm_hash).ok_or(DnaError::InvalidWasmHash)
    }

    #[deprecated = "remove after app bundles become standard; use DnaBundle instead"]
    /// Render this dna_file as bytecode to send over the wire, or store in a file.
    pub async fn to_file_content(&self) -> Result<Vec<u8>, DnaError> {
        // Not super efficient memory-wise, but doesn't block any threads
        let dna_file = self.clone();
        dna_file.verify_hash()?;
        // Block because gzipping could take some time
        tokio::task::spawn_blocking(move || {
            let data: SerializedBytes = dna_file.try_into()?;
            let mut enc = flate2::write::GzEncoder::new(Vec::new(), flate2::Compression::default());
            use std::io::Write;
            enc.write_all(data.bytes())?;
            Ok(enc.finish()?)
        })
        .await
        .expect("blocking thread panic!d - panicing here too")
    }

pub async fn from_file_content(data: &[u8]) -> Result<Self, DnaError>

👎Deprecated: remove after app bundles become standard; use DnaBundle instead

Load dna_file bytecode into this rust struct.

pub async fn with_properties(self, properties: SerializedBytes) -> Self

Transform this DnaFile into a new DnaFile with different properties and, hence, a different DnaHash.

pub async fn with_network_seed(self, network_seed: NetworkSeed) -> Self

Transform this DnaFile into a new DnaFile with a different network seed and, hence, a different DnaHash.

pub fn code(&self) -> &BTreeMap<WasmHash, DnaWasm>

The bytes of the WASM zomes referenced in the Dna portion.

pub fn get_wasm_for_zome(
    &self,
    zome_name: &ZomeName
) -> Result<&DnaWasm, DnaError>

Fetch the Webassembly byte code for a zome.

pub async fn to_file_content(&self) -> Result<Vec<u8>, DnaError>

👎Deprecated: remove after app bundles become standard; use DnaBundle instead

Render this dna_file as bytecode to send over the wire, or store in a file.

pub fn set_name(&self, name: String) -> Self

Set the DNA’s name.

pub fn update_modifiers(&self, dna_modifiers: DnaModifiersOpt) -> Self

Change the DNA modifiers – the network seed, origin time and properties – while leaving the actual DNA code intact.

Trait Implementations

impl Clone for DnaFile

fn clone(&self) -> DnaFile

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for DnaFile

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for DnaFile

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>where
    __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl From<DnaFile> for (DnaDef, Vec<DnaWasm>)

fn from(dna_file: DnaFile) -> (DnaDef, Vec<DnaWasm>)

Converts to this type from the input type.

impl PartialEq<DnaFile> for DnaFile

fn eq(&self, other: &DnaFile) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for DnaFile

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>where
    __S: Serializer,

Serialize this value into the given Serde serializer.

impl TryFrom<&DnaFile> for SerializedBytes

type Error = SerializedBytesError

The type returned in the event of a conversion error.

fn try_from(t: &DnaFile) -> Result<SerializedBytes, SerializedBytesError>

Performs the conversion.

impl TryFrom<DnaFile> for SerializedBytes

type Error = SerializedBytesError

The type returned in the event of a conversion error.

fn try_from(t: DnaFile) -> Result<SerializedBytes, SerializedBytesError>

Performs the conversion.

impl TryFrom<SerializedBytes> for DnaFile

type Error = SerializedBytesError

The type returned in the event of a conversion error.

fn try_from(sb: SerializedBytes) -> Result<DnaFile, SerializedBytesError>

Performs the conversion.

impl Eq for DnaFile

impl StructuralEq for DnaFile

impl StructuralPartialEq for DnaFile