Skip to content

Commit a3857f7

Browse files
committed
add documentation
1 parent e50589b commit a3857f7

File tree

1 file changed

+21
-0
lines changed

1 file changed

+21
-0
lines changed

src/cargo/util/auth.rs

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -442,26 +442,44 @@ fn auth_token_optional(
442442
Ok(Some(token))
443443
}
444444

445+
/// A record of what kind of operation is happening that we should generate a token for.
445446
pub enum Mutation<'a> {
447+
/// Before we generate a crate file for the users attempt to publish,
448+
/// we need to check if we are configured correctly to generate a token.
449+
/// This variant is used to make sure that we can generate a token,
450+
/// to error out early if the token is not configured correctly.
446451
PrePublish,
452+
/// The user is attempting to publish a crate.
447453
Publish {
454+
/// The name of the crate
448455
name: &'a str,
456+
/// The version of the crate
449457
vers: &'a str,
458+
/// The checksum of the crate file being uploaded
450459
cksum: &'a str,
451460
},
461+
/// The user is attempting to yank a crate.
452462
Yank {
463+
/// The name of the crate
453464
name: &'a str,
465+
/// The version of the crate
454466
vers: &'a str,
455467
},
468+
/// The user is attempting to unyank a crate.
456469
Unyank {
470+
/// The name of the crate
457471
name: &'a str,
472+
/// The version of the crate
458473
vers: &'a str,
459474
},
475+
/// The user is attempting to unyank a crate.
460476
Owners {
477+
/// The name of the crate
461478
name: &'a str,
462479
},
463480
}
464481

482+
/// The main body of an asymmetric token as describe in RFC 3231.
465483
#[derive(serde::Serialize)]
466484
struct Message<'a> {
467485
iat: &'a str,
@@ -477,9 +495,11 @@ struct Message<'a> {
477495
cksum: Option<&'a str>,
478496
#[serde(skip_serializing_if = "Option::is_none")]
479497
challenge: Option<&'a str>,
498+
/// This field is not yet used. This field can be set to a value >1 to indicate a breaking change in the token format.
480499
#[serde(skip_serializing_if = "Option::is_none")]
481500
v: Option<u8>,
482501
}
502+
/// The footer of an asymmetric token as describe in RFC 3231.
483503
#[derive(serde::Serialize)]
484504
struct Footer<'a> {
485505
url: &'a str,
@@ -509,6 +529,7 @@ pub fn login(config: &Config, sid: &SourceId, token: RegistryCredentialConfig) -
509529
Ok(())
510530
}
511531

532+
/// Checks that a secret key is valid, and returns the associated public key in Paserk format.
512533
pub(crate) fn paserk_public_from_paserk_secret(secret_key: &str) -> Option<String> {
513534
let secret: AsymmetricSecretKey<pasetors::version3::V3> = secret_key.try_into().ok()?;
514535
let public: AsymmetricPublicKey<pasetors::version3::V3> = (&secret).try_into().ok()?;

0 commit comments

Comments
 (0)