holochain_conductor_api/

admin_interface.rs

use crate::peer_meta::PeerMetaInfo;
use crate::{AppInfo, FullStateDump, StorageInfo};
use holo_hash::*;
use holochain_types::prelude::*;
use holochain_types::websocket::AllowedOrigins;
use holochain_zome_types::cell::CellId;
use kitsune2_api::Url;
use std::collections::{BTreeMap, HashMap};

/// Represents the available conductor functions to call over an admin interface.
///
/// Enum variants follow a general convention of `verb_noun` as opposed to
/// the `noun_verb` of responses.
///
/// # Errors
///
/// Returns an [`AdminResponse::Error`] with a reason why the request failed.
// Expects a serialized object with any contents of the enum on a key `data`
// and the enum variant on a key `type`, e.g.
// `{ type: 'enable_app', data: { installed_app_id: 'test_app' } }`
#[derive(Debug, serde::Serialize, serde::Deserialize, SerializedBytes)]
#[serde(tag = "type", content = "value", rename_all = "snake_case")]
pub enum AdminRequest {
    /// Set up and register one or more new admin interfaces
    /// as specified by a list of configurations.
    ///
    /// # Returns
    ///
    /// [`AdminResponse::AdminInterfacesAdded`]
    AddAdminInterfaces(Vec<crate::config::AdminInterfaceConfig>),

    /// Get the definition of a Cell.
    ///
    /// # Returns
    ///
    /// [`AdminResponse::DnaDefinitionReturned`]
    GetDnaDefinition(Box<CellId>),

    /// Update coordinator zomes for an already installed DNA.
    ///
    /// Replaces any installed coordinator zomes with the same zome name.
    /// If the zome name doesn't exist then the coordinator zome is appended
    /// to the current list of coordinator zomes.
    ///
    /// # Returns
    ///
    /// [`AdminResponse::CoordinatorsUpdated`]
    UpdateCoordinators(Box<UpdateCoordinatorsPayload>),

    /// Install an app using an [`AppBundle`].
    ///
    /// Triggers genesis to be run on all Cells and to be stored.
    /// An app is intended for use by
    /// one and only one Agent and for that reason it takes an `AgentPubKey` and
    /// installs all the DNAs with that `AgentPubKey`, forming new cells.
    /// See [`InstallAppPayload`] for full details on the configuration.
    ///
    /// Note that the new app will not be enabled automatically after installation
    /// and can be enabled by calling [`EnableApp`].
    ///
    /// # Returns
    ///
    /// [`AdminResponse::AppInstalled`]
    ///
    /// [`EnableApp`]: AdminRequest::EnableApp
    InstallApp(Box<InstallAppPayload>),

    /// Uninstalls the app specified by argument `installed_app_id` from the conductor.
    ///
    /// The app will be removed from the list of installed apps, and any cells
    /// which were referenced only by this app will be disabled and removed, clearing up
    /// any persisted data.
    /// Cells which are still referenced by other installed apps will not be removed.
    ///
    /// # Returns
    ///
    /// [`AdminResponse::AppUninstalled`]
    UninstallApp {
        /// The app ID to uninstall
        installed_app_id: InstalledAppId,

        /// If anything would prevent this app from being uninstalled, such as the existence
        /// of protected dependency to one of its cells, this flag will force the uninstallation.
        /// This will generally lead to bad outcomes, and should not be used unless you're
        /// aware of the consequences.
        #[serde(default)]
        force: bool,
    },

    /// List the hashes of all installed DNAs.
    ///
    /// # Returns
    ///
    /// [`AdminResponse::DnasListed`]
    ListDnas,

    /// Generate a new [`AgentPubKey`].
    ///
    /// # Returns
    ///
    /// [`AdminResponse::AgentPubKeyGenerated`]
    GenerateAgentPubKey,

    /// List the IDs of all live cells currently running in the conductor.
    ///
    /// # Returns
    ///
    /// [`AdminResponse::CellIdsListed`]
    ListCellIds,

    /// List the apps and their information that are installed in the conductor.
    ///
    /// Results are sorted by the `installed_at` timestamp of the app, in descending order.
    ///
    /// If `status_filter` is `Some(_)`, it will return only the apps with the specified status.
    ///
    /// # Returns
    ///
    /// [`AdminResponse::AppsListed`]
    ListApps {
        /// An optional status to filter the list of apps by
        status_filter: Option<AppStatusFilter>,
    },

    /// Changes the specified app from a disabled to an enabled state in the conductor.
    ///
    /// It is likely to want to call this after calling [`AdminRequest::InstallApp`], since a freshly
    /// installed app is not enabled automatically. Once the app is enabled,
    /// zomes can be immediately called and it will also be loaded and enabled automatically on any reboot of the conductor.
    ///
    /// This call is idempotent. If the app is already enabled, the call will be a no-op
    /// and just return the already enabled app info.
    ///
    /// # Returns
    ///
    /// [`AdminResponse::AppEnabled`]
    EnableApp {
        /// The app ID to enable
        installed_app_id: InstalledAppId,
    },

    /// Changes the specified app from an enabled to a disabled state in the conductor.
    ///
    /// When an app is disabled, zome calls can no longer be made, and the app will not be
    /// enabled on a reboot of the conductor.
    ///
    /// This call is idempotent. If the app is already disabled, the call will be a no-op
    /// and just return the already disabled app info.
    ///
    /// # Returns
    ///
    /// [`AdminResponse::AppDisabled`]
    DisableApp {
        /// The app ID to disable
        installed_app_id: InstalledAppId,
    },

    /// Open up a new websocket for processing [`AppRequest`]s. Any active app will be
    /// callable via the attached app interface.
    ///
    /// **NB:** App interfaces are persisted when shutting down the conductor and are
    /// restored when restarting the conductor. Unused app interfaces are _not_ cleaned
    /// up. It is therefore recommended to reuse existing interfaces. They can be queried
    /// with the call [`AdminRequest::ListAppInterfaces`].
    ///
    /// # Returns
    ///
    /// [`AdminResponse::AppInterfaceAttached`]
    ///
    /// # Arguments
    ///
    /// Optionally a `port` parameter can be passed to this request. If it is `None`,
    /// a free port is chosen by the conductor.
    ///
    /// An `allowed_origins` parameter to control which origins are allowed to connect
    /// to the app interface.
    ///
    /// [`AppRequest`]: super::AppRequest
    AttachAppInterface {
        /// Optional port number
        port: Option<u16>,

        /// An optional address to bind the interface to.
        ///
        /// This is dangerous to set to anything other than `localhost`. If no value is set then
        /// the interface will bind to `localhost`.
        ///
        /// Holochain has minimal security protections in place for websocket connections. The app
        /// websockets are protected by the admin websocket, but if you expose the admin websocket
        /// to the network, then anyone who can connect to it can control your conductor.
        danger_bind_addr: Option<String>,

        /// Allowed origins for this app interface.
        ///
        /// This should be one of:
        /// - A comma-separated list of origins - `http://localhost:3000,http://localhost:3001`,
        /// - A single origin - `http://localhost:3000`,
        /// - Any origin - `*`
        ///
        /// Connections from any origin which is not permitted by this config will be rejected.
        allowed_origins: AllowedOrigins,

        /// Optionally bind this app interface to a specific installed app.
        ///
        /// If this is `None` then the interface can be used to establish a connection for any app.
        ///
        /// If this is `Some` then the interface will only accept connections for the specified app.
        /// Those connections will only be able to make calls to and receive signals from that app.
        installed_app_id: Option<InstalledAppId>,
    },

    /// List all the app interfaces currently attached with [`AttachAppInterface`].
    ///
    /// # Returns
    ///
    /// [`AdminResponse::AppInterfacesListed`], a list of websocket ports that can
    /// process [`AppRequest`]s.
    ///
    /// [`AttachAppInterface`]: AdminRequest::AttachAppInterface
    /// [`AppRequest`]: super::AppRequest
    ListAppInterfaces,

    /// Dump the state of the cell specified by argument `cell_id`,
    /// including its chain, as a string containing JSON.
    ///
    /// # Returns
    ///
    /// [`AdminResponse::StateDumped`]
    DumpState {
        /// The cell ID for which to dump state
        cell_id: Box<CellId>,
    },

    /// Dump the state of the conductor, including the in-memory representation
    /// and the persisted ConductorState, as JSON.
    ///
    /// # Returns
    ///
    /// [`AdminResponse::ConductorStateDumped`]
    DumpConductorState,

    /// Dump the full state of the Cell specified by argument `cell_id`,
    /// including its chain and DHT shard, as a string containing JSON.
    ///
    /// **Warning**: this API call is subject to change, and will not be available to hApps.
    /// This is meant to be used by introspection tooling.
    ///
    /// Note that the response to this call can be very big, as it's requesting for
    /// the full database of the cell.
    ///
    /// Also note that while DHT ops about private entries will be returned (like `StoreRecord`),
    /// the entry in itself will be missing, as it's not actually stored publicly in the DHT shard.
    ///
    /// # Returns
    ///
    /// [`AdminResponse::FullStateDumped`]
    DumpFullState {
        /// The cell ID for which to dump the state
        cell_id: Box<CellId>,
        /// The last seen DhtOp RowId, returned in the full dump state.
        /// Only DhtOps with RowId greater than the cursor will be returned.
        dht_ops_cursor: Option<u64>,
    },

    /// Dump the network metrics tracked by kitsune.
    ///
    /// # Returns
    ///
    /// [`AdminResponse::NetworkMetricsDumped`]
    DumpNetworkMetrics {
        /// If set, limits the metrics dumped to a single DNA hash space.
        #[serde(default)]
        dna_hash: Option<DnaHash>,

        /// Whether to include a DHT summary.
        ///
        /// You need a dump from multiple nodes in order to make a comparison, so this is not
        /// requested by default.
        #[serde(default)]
        include_dht_summary: bool,
    },

    /// Dump network statistics from the Kitsune2 networking transport module.
    ///
    /// # Returns
    ///
    /// [`AdminResponse::NetworkStatsDumped`]
    DumpNetworkStats,

    /// Add a list of agents to this conductor's peer store.
    ///
    /// This is a way of shortcutting peer discovery and is useful for testing.
    ///
    /// It is also helpful if you know other
    /// agents on the network and they can send you
    /// their agent info.
    ///
    /// # Returns
    ///
    /// [`AdminResponse::AgentInfoAdded`]
    AddAgentInfo {
        /// list of signed agent info to add to peer store
        agent_infos: Vec<String>,
    },

    /// Request the [`kitsune2_api::AgentInfoSigned`] stored in this conductor's
    /// peer store.
    ///
    /// You can:
    /// - Get all agent info by leaving `dna_hashes` to `None`.
    /// - Get agent info for specific dna hashes by setting the `dna_hashes` argument.
    ///
    /// This is how you can send your agent info to another agent.
    /// It is also useful for testing across networks.
    ///
    /// # Returns
    ///
    /// [`AdminResponse::AgentInfo`]
    AgentInfo {
        /// Optionally choose the agent infos of a set of Dnas.
        dna_hashes: Option<Vec<DnaHash>>,
    },

    /// Request the contents of the peer meta store(s) related to
    /// the given dna hashes for the agent at the given Url.
    ///
    /// If `dna_hashes` is set to `None` it returns the contents
    /// for all dnas that the agent is part of.
    ///
    /// # Returns
    ///
    /// [`AdminResponse::PeerMetaInfo`]
    PeerMetaInfo {
        url: Url,
        dna_hashes: Option<Vec<DnaHash>>,
    },

    /// "Graft" [`Record`]s onto the source chain of the specified [`CellId`].
    ///
    /// The records must form a valid chain segment (ascending sequence numbers,
    /// and valid `prev_action` references). If the first record contains a `prev_action`
    /// which matches the existing records, then the new records will be "grafted" onto
    /// the existing chain at that point, and any other records following that point which do
    /// not match the new records will be removed.
    ///
    /// If this operation is called when there are no forks, the final state will also have
    /// no forks.
    ///
    /// **BEWARE** that this may result in the deletion of data! Any existing records which form
    /// a fork with respect to the new records will be deleted.
    ///
    /// All records must be authored and signed by the same agent.
    /// The [`DnaFile`] (but not necessarily the cell) must already be installed
    /// on this conductor.
    ///
    /// Care is needed when using this command as it can result in
    /// an invalid chain.
    /// Additionally, if conflicting source chain records are
    /// inserted on different nodes, then the chain will be forked.
    ///
    /// If an invalid or forked chain is inserted
    /// and then pushed to the DHT, it can't be undone.
    ///
    /// Note that the cell does not need to exist to run this command.
    /// It is possible to insert records into a source chain before
    /// the cell is created. This can be used to restore from backup.
    ///
    /// If the cell is installed, it is best to call [`AdminRequest::DisableApp`]
    /// before running this command, as otherwise the chain head may move.
    /// If `truncate` is true, the chain head is not checked and any new
    /// records will be lost.
    ///
    /// # Returns
    ///
    /// [`AdminResponse::RecordsGrafted`]
    GraftRecords {
        /// The cell that the records are being inserted into.
        cell_id: CellId,
        /// If this is `true`, then the records will be validated before insertion.
        /// This is much slower but is useful for verifying the chain is valid.
        ///
        /// If this is `false`, then records will be inserted as is.
        /// This could lead to an invalid chain.
        validate: bool,
        /// The records to be inserted into the source chain.
        records: Vec<Record>,
    },

    /// Request capability grant for making zome calls.
    ///
    /// # Returns
    ///
    /// [`AdminResponse::ZomeCallCapabilityGranted`]
    GrantZomeCallCapability(Box<GrantZomeCallCapabilityPayload>),

    /// Revoke a capability grant.
    ///
    /// You have to provide the [`ActionHash`] of the capability grant to revoke and the [`CellId`] of the cell
    /// the capability grant is for.
    ///
    /// # Returns
    ///
    /// [`AdminResponse::ZomeCallCapabilityRevoked`]
    RevokeZomeCallCapability {
        action_hash: ActionHash,
        cell_id: CellId,
    },

    /// Request capability grant info for all cells in the app.
    ///
    /// # Returns
    ///
    /// [`AdminResponse::CapabilityGrantsInfo`]
    ListCapabilityGrants {
        installed_app_id: String,
        include_revoked: bool,
    },

    /// Delete a clone cell that was previously disabled.
    ///
    /// # Returns
    ///
    /// [`AdminResponse::CloneCellDeleted`]
    DeleteCloneCell(Box<DeleteCloneCellPayload>),

    /// Info about storage used by apps
    ///
    /// # Returns
    ///
    /// [`AdminResponse::StorageInfo`]
    StorageInfo,

    /// Connecting to an app over an app websocket requires an authentication token. This endpoint
    /// is used to issue those tokens for use by app clients.
    ///
    /// # Returns
    ///
    /// [`AdminResponse::AppAuthenticationTokenIssued`]
    IssueAppAuthenticationToken(IssueAppAuthenticationTokenPayload),

    /// Revoke an issued app authentication token.
    ///
    /// # Returns
    ///
    /// [`AdminResponse::AppAuthenticationTokenRevoked`]
    RevokeAppAuthenticationToken(AppAuthenticationToken),

    /// Find installed cells which use a DNA that's forward-compatible with the given DNA hash.
    /// Namely, this finds cells with DNAs whose manifest lists the given DNA hash in its `lineage` field.
    #[cfg(feature = "unstable-migration")]
    GetCompatibleCells(DnaHash),
}

/// Represents the possible responses to an [`AdminRequest`]
/// and follows a general convention of `noun_verb` as opposed to
/// the `verb_noun` of `AdminRequest`.
///
/// Will serialize as an object with any contents of the enum on a key `data`
/// and the enum variant on a key `type`, e.g.
/// `{ type: 'app_interface_attached', data: { port: 4000 } }`
#[derive(Debug, serde::Serialize, serde::Deserialize, SerializedBytes)]
#[cfg_attr(test, derive(Clone))]
#[serde(tag = "type", content = "value", rename_all = "snake_case")]
pub enum AdminResponse {
    /// Can occur in response to any [`AdminRequest`].
    ///
    /// There has been an error during the handling of the request.
    Error(ExternalApiWireError),

    /// The successful response to an [`AdminRequest::GetDnaDefinition`]
    DnaDefinitionReturned(DnaDef),

    /// The successful response to an [`AdminRequest::UpdateCoordinators`]
    CoordinatorsUpdated,

    /// The successful response to an [`AdminRequest::InstallApp`].
    ///
    /// The resulting [`AppInfo`] contains the app ID,
    /// the [`RoleName`]s and, most usefully, [`CellInfo`](crate::CellInfo)s
    /// of the newly installed DNAs.
    AppInstalled(AppInfo),

    /// The successful response to an [`AdminRequest::UninstallApp`].
    ///
    /// It means the app was uninstalled successfully.
    AppUninstalled,

    /// The successful response to an [`AdminRequest::AddAdminInterfaces`].
    ///
    /// It means the `AdminInterface`s have successfully been added.
    AdminInterfacesAdded,

    /// The successful response to an [`AdminRequest::GenerateAgentPubKey`].
    ///
    /// Contains a new [`AgentPubKey`] generated by the keystore.
    AgentPubKeyGenerated(AgentPubKey),

    /// The successful response to an [`AdminRequest::ListDnas`].
    ///
    /// Contains a list of the hashes of all installed DNAs.
    DnasListed(Vec<DnaHash>),

    /// The successful response to an [`AdminRequest::ListCellIds`].
    ///
    /// Contains a list of all the cell IDs in the conductor.
    CellIdsListed(Vec<CellId>),

    /// The successful response to an [`AdminRequest::ListApps`].
    ///
    /// Contains a list of the `InstalledAppInfo` of the installed apps in the conductor.
    AppsListed(Vec<AppInfo>),

    /// The successful response to an [`AdminRequest::AttachAppInterface`].
    ///
    /// Contains the port number of the attached app interface.
    AppInterfaceAttached {
        /// Networking port of the new `AppInterfaceApi`
        port: u16,
    },

    /// The list of attached app interfaces.
    AppInterfacesListed(Vec<AppInterfaceInfo>),

    /// The successful response to an [`AdminRequest::EnableApp`].
    ///
    /// If anything during the process of enabling the app fails,
    /// the error is returned and the app remains disabled.
    /// In case of failure to join the network of any of the app's
    /// cells, it can be re-attempted to enable the app.
    ///
    /// Contains the app info of the enabled app.
    AppEnabled(AppInfo),

    /// The successful response to an [`AdminRequest::DisableApp`].
    ///
    /// It means the app was disabled successfully.
    AppDisabled,

    /// The successful response to an [`AdminRequest::DumpState`].
    ///
    /// The result contains a string of serialized JSON data which can be deserialized to access the
    /// full state dump and inspect the source chain.
    StateDumped(String),

    /// The successful response to an [`AdminRequest::DumpFullState`].
    ///
    /// The result contains a string of serialized JSON data which can be deserialized to access the
    /// full state dump and inspect the source chain.
    ///
    /// Note that this result can be very big, as it's requesting the full database of the cell.
    FullStateDumped(FullStateDump),

    /// The successful response to an [`AdminRequest::DumpConductorState`].
    ///
    /// Simply a JSON serialized snapshot of `Conductor` and `ConductorState` from the `holochain` crate.
    ConductorStateDumped(String),

    /// The successful result of a call to [`AdminRequest::DumpNetworkMetrics`].
    NetworkMetricsDumped(HashMap<DnaHash, Kitsune2NetworkMetrics>),

    /// The successful result of a call to [`AdminRequest::DumpNetworkStats`].
    NetworkStatsDumped(kitsune2_api::ApiTransportStats),

    /// The successful response to an [`AdminRequest::AddAgentInfo`].
    ///
    /// This means the agent info was successfully added to the peer store.
    AgentInfoAdded,

    /// The successful response to an [`AdminRequest::AgentInfo`].
    ///
    /// This is all the agent info that was found for the request.
    AgentInfo(Vec<String>),

    /// The successful response to an [`AdminRequest::PeerMetaInfo`].
    ///
    /// A JSON formatted string.
    PeerMetaInfo(BTreeMap<DnaHash, BTreeMap<String, PeerMetaInfo>>),

    /// The successful response to an [`AdminRequest::GraftRecords`].
    RecordsGrafted,

    /// The successful response to an [`AdminRequest::GrantZomeCallCapability`].
    ///
    /// Returns the [`ActionHash`] of the capability grant.
    ZomeCallCapabilityGranted(ActionHash),

    /// The successful response to an [`AdminRequest::RevokeZomeCallCapability`].
    ZomeCallCapabilityRevoked,

    /// The successful response to an [`AdminRequest::ListCapabilityGrants`].
    CapabilityGrantsInfo(AppCapGrantInfo),

    /// The successful response to an [`AdminRequest::DeleteCloneCell`].
    CloneCellDeleted,

    /// The successful response to an [`AdminRequest::StorageInfo`].
    StorageInfo(StorageInfo),

    /// The successful response to an [`AdminRequest::IssueAppAuthenticationToken`].
    AppAuthenticationTokenIssued(AppAuthenticationTokenIssued),

    /// The successful response to an [`AdminRequest::RevokeAppAuthenticationToken`].
    AppAuthenticationTokenRevoked,

    /// The successful response to an [`AdminRequest::GetCompatibleCells`].
    #[cfg(feature = "unstable-migration")]
    CompatibleCells(CompatibleCells),
}

#[cfg(feature = "unstable-migration")]
pub type CompatibleCells =
    std::collections::BTreeSet<(InstalledAppId, std::collections::BTreeSet<CellId>)>;

/// Error type that goes over the websocket wire.
/// This intends to be application developer facing
/// so it should be readable and relevant
#[derive(Debug, serde::Serialize, serde::Deserialize, SerializedBytes, Clone)]
#[serde(tag = "type", content = "value", rename_all = "snake_case")]
pub enum ExternalApiWireError {
    // TODO: B-01506 Constrain these errors so they are relevant to
    // application developers and what they would need
    // to react to using code (i.e. not just print)
    /// Any internal error
    InternalError(String),
    /// The input to the API failed to deseralize.
    Deserialization(String),
    /// The DNA path provided was invalid.
    DnaReadError(String),
    /// There was an error in the ribosome.
    RibosomeError(String),
    /// The zome call failed authentication.
    ///
    /// [How to sign zome calls.](crate::AppRequest::CallZome)
    ZomeCallAuthenticationFailed(String),
    /// The zome call is unauthorized.
    ZomeCallUnauthorized(String),
    /// A countersigning session has failed.
    CountersigningSessionError(String),
}

impl ExternalApiWireError {
    /// Convert the error from the display.
    pub fn internal<T: std::fmt::Display>(e: T) -> Self {
        // Display format is used because
        // this version intended for users.
        ExternalApiWireError::InternalError(e.to_string())
    }
}

/// Filter for [`AdminRequest::ListApps`].
///
/// Apps can be either enabled or disabled, set by the user via the conductor interface.
#[derive(Debug, serde::Serialize, serde::Deserialize, SerializedBytes, Clone)]
#[serde(rename_all = "snake_case")]
pub enum AppStatusFilter {
    /// Filter on apps which are Enabled.
    Enabled,
    /// Filter on apps which are Disabled.
    Disabled,
}

/// Informational response for listing app interfaces.
#[derive(Debug, serde::Serialize, serde::Deserialize, SerializedBytes, Clone)]
pub struct AppInterfaceInfo {
    /// The port that the app interface is listening on.
    pub port: u16,

    /// The allowed origins for this app interface.
    pub allowed_origins: AllowedOrigins,

    /// The optional association with a specific installed app.
    pub installed_app_id: Option<InstalledAppId>,
}

/// Request payload for [AdminRequest::IssueAppAuthenticationToken].
#[derive(Debug, serde::Serialize, serde::Deserialize)]
pub struct IssueAppAuthenticationTokenPayload {
    /// The app ID to issue a connection token for.
    pub installed_app_id: InstalledAppId,

    /// The number of seconds that the token should be valid for. After this number of seconds, the
    /// token will no longer be accepted by the conductor.
    ///
    /// This is 30s by default which is reasonably high but with [IssueAppAuthenticationTokenPayload::single_use]
    /// set to `true`, the token will be invalidated after the first use anyway.
    ///
    /// Set this to 0 to create a token that does not expire.
    #[serde(default = "default_expiry_seconds")]
    pub expiry_seconds: u64,

    /// Whether the token should be single-use. This is `true` by default and will cause the token
    /// to be invalidated after the first use, irrespective of connection success.
    ///
    /// Set this to `false` to allow the token to be used multiple times.
    #[serde(default = "default_single_use")]
    pub single_use: bool,
}

fn default_expiry_seconds() -> u64 {
    30
}

fn default_single_use() -> bool {
    true
}

impl IssueAppAuthenticationTokenPayload {
    /// Create a new payload for issuing a connection token for the specified app.
    ///
    /// The token will be valid for 30 seconds and for a single use.
    pub fn for_installed_app_id(installed_app_id: InstalledAppId) -> Self {
        installed_app_id.into()
    }

    /// Set the expiry time for the token.
    pub fn expiry_seconds(mut self, expiry_seconds: u64) -> Self {
        self.expiry_seconds = expiry_seconds;
        self
    }

    /// Set whether the token should be single-use.
    pub fn single_use(mut self, single_use: bool) -> Self {
        self.single_use = single_use;
        self
    }
}

impl From<InstalledAppId> for IssueAppAuthenticationTokenPayload {
    fn from(installed_app_id: InstalledAppId) -> Self {
        // Defaults here should match the serde defaults in the struct definition
        Self {
            installed_app_id,
            expiry_seconds: 30,
            single_use: true,
        }
    }
}

/// A token issued by the conductor that can be used to authenticate a connection to an app interface.
pub type AppAuthenticationToken = Vec<u8>;

/// Response payload for [AdminResponse::AppAuthenticationTokenIssued].
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
pub struct AppAuthenticationTokenIssued {
    /// A token issued by the conductor that can be used to authenticate a connection to an app interface.
    /// This is expected to be passed from the caller of the admin interface to the client that will
    /// use the app interface. It should be treated as secret and kept from other parties.
    pub token: AppAuthenticationToken,

    /// The timestamp after which Holochain will consider the token invalid. This should be
    /// considered informational only and the client should not rely on the token being accepted
    /// following a client-side check that the token has not yet expired.
    ///
    /// If the token was created with [IssueAppAuthenticationTokenPayload::expiry_seconds] set to `0`
    /// then this field will be `None`.
    // TODO Kitsune type used in the conductor interface
    pub expires_at: Option<Timestamp>,
}

#[cfg(test)]
mod tests {
    use crate::{AdminRequest, AdminResponse, ExternalApiWireError};
    use serde::Deserialize;

    #[test]
    fn admin_request_serialization() {
        use rmp_serde::Deserializer;

        // make sure requests are serialized as expected
        let request = AdminRequest::DisableApp {
            installed_app_id: "some_id".to_string(),
        };
        let serialized_request = holochain_serialized_bytes::encode(&request).unwrap();
        assert_eq!(
            serialized_request,
            vec![
                130, 164, 116, 121, 112, 101, 171, 100, 105, 115, 97, 98, 108, 101, 95, 97, 112,
                112, 165, 118, 97, 108, 117, 101, 129, 176, 105, 110, 115, 116, 97, 108, 108, 101,
                100, 95, 97, 112, 112, 95, 105, 100, 167, 115, 111, 109, 101, 95, 105, 100
            ]
        );

        let json_expected = r#"{"type":"disable_app","value":{"installed_app_id":"some_id"}}"#;
        let mut deserializer = Deserializer::new(&*serialized_request);
        let json_value: serde_json::Value = Deserialize::deserialize(&mut deserializer).unwrap();
        let json_actual = serde_json::to_string(&json_value).unwrap();

        assert_eq!(json_actual, json_expected);

        // make sure responses are serialized as expected
        let response = AdminResponse::Error(ExternalApiWireError::RibosomeError(
            "error_text".to_string(),
        ));
        let serialized_response = holochain_serialized_bytes::encode(&response).unwrap();
        assert_eq!(
            serialized_response,
            vec![
                130, 164, 116, 121, 112, 101, 165, 101, 114, 114, 111, 114, 165, 118, 97, 108, 117,
                101, 130, 164, 116, 121, 112, 101, 174, 114, 105, 98, 111, 115, 111, 109, 101, 95,
                101, 114, 114, 111, 114, 165, 118, 97, 108, 117, 101, 170, 101, 114, 114, 111, 114,
                95, 116, 101, 120, 116
            ]
        );

        let json_expected =
            r#"{"type":"error","value":{"type":"ribosome_error","value":"error_text"}}"#;
        let mut deserializer = Deserializer::new(&*serialized_response);
        let json_value: serde_json::Value = Deserialize::deserialize(&mut deserializer).unwrap();
        let json_actual = serde_json::to_string(&json_value).unwrap();

        assert_eq!(json_actual, json_expected);
    }
}