Misleading documentation prose for key value purge

[corbinu]

Make sure that these boxes are checked before submitting your issue -- thank you!

• [x] Included below version and environment information
• [x] Included a [Minimal, Complete, and Verifiable example] (https://stackoverflow.com/help/mcve)

NATS version (grep 'name = "nats"' Cargo.lock -A 1)

name = "async-nats" version = "0.21.0"

rustc version (rustc --version - we support Rust 1.41 and up)

rustc 1.64.0 (a55dd71d5 2022-09-19)

OS/Container environment:

Distributor ID: Ubuntu
Description:    Ubuntu 22.04.1 LTS
Release:    22.04
Codename:   jammy

5.15.0-52-generic

Steps or code to reproduce the issue:

#[tokio::main]
async fn main() -> Result<(), async_nats::Error> {
    let client = async_nats::connect("nats://localhost:4222").await?;

    let jetstream = async_nats::jetstream::new(client);

    let kv = jetstream.get_key_value("kv").await?;

    kv.put("key_to_purge", "foo".into()).await?;
    kv.put("key_to_purge", "bar".into()).await?;

    kv.purge("key_to_purge").await?;

    let entry = kv.entry("key_to_purge").await?;

    println!("{:?}", entry);

    Ok(())
}

Expected result:

According to the purge documentation a purge "Purges the given key, destructively removing everything from the bucket.". Key should be fully removed from the bucket.

stdout is:

None

Actual result:

Only the keys history is purged from the bucket not the key itself.

stdout is:

Some(Entry { bucket: "kv", key: "key_to_purge", value: [], revision: 3, delta: 0, created: (datetime when command was run), operation: Put })

[caspervonb]

Believe this is a documentation issue, if I recall correctly purge removes all revisions and places a single delete marker.

[Jarema]

@caspervonb is correct.

Will check though if we should "hide" the records on entry, or only on get as we do now.

[caspervonb]

Will check though if we should "hide" the records on entry, or only on get as we do now.

Get should ignore markers and return None, but entries iterator should keep markers? If I recall correctly that is the behavior I had in the sync client.

[corbinu]

@caspervonb This actually still is a bug as .get( returns Some([]) rather than None. Should I open a separate issue for that? Or update the reproduction here?

[caspervonb]

Closing, as the following produces expected result

#[tokio::main]
async fn main() {
    let client = async_nats::connect("nats://localhost:4222").await.unwrap();

    let jetstream = async_nats::jetstream::new(client);

    let kv = jetstream.get_key_value("kv").await.unwrap();

    kv.put("key_to_purge", "foo".into()).await.unwrap();
    kv.purge("key_to_purge").await.unwrap();

    let maybe_value = kv.get("key_to_purge").await.unwrap();
    println!("value is {:?}", maybe_value);
}