diff --git a/content/meta.json b/content/meta.json index c4dc973..25bf45d 100644 --- a/content/meta.json +++ b/content/meta.json @@ -12,6 +12,7 @@ "sdks/c", "sdks/python", "sdks/rust-std", - "sdks/rust-no-std" + "sdks/rust-no-std", + "sdks/go" ] } \ No newline at end of file diff --git a/content/sdks/go.mdx b/content/sdks/go.mdx new file mode 100644 index 0000000..dbaa0fe --- /dev/null +++ b/content/sdks/go.mdx @@ -0,0 +1,4 @@ +--- +title: Go +icon: SiGo +--- \ No newline at end of file diff --git a/content/sdks/rust-no-std.mdx b/content/sdks/rust-no-std.mdx index 1ae7e05..7eed0a8 100644 --- a/content/sdks/rust-no-std.mdx +++ b/content/sdks/rust-no-std.mdx @@ -1,4 +1,87 @@ --- title: Rust (No STD) icon: SiRust ---- \ No newline at end of file +--- + +Welcome to the Rust (no STD) SDK documentation! This crate does not require the standard library to +compile. It's considerably slower than the STD-enabled SDK, up to x4 slower. If you can use the STD +crate, choose it. + +## Quick Start + +Before you can integrate Duckity into your application, you'll need to have the following: + +1. An application, +2. At least one protection profile created in that application, and +3. The ID of the protection profile(s) to use + +If you're missing either of those, head over to the [Duckity Dashboard](https://app.duckity.com) or +read the [Quick Start](/quick-start) guide to learn how to set those up. + +Once you got those ready, follow these steps to get things running on your client: + +### Install the SDK [step] + +To install the SDK in your project, run the following command in your shell: + +```sh +cargo install duckity-core +``` + +### Get a Challenge [step] + +This crate does not include utilities to fetch challenges. To get a challenge, make a POST HTTP +request like the following: + +```http +GET /v1/challenges/{protection-profile-id}/issue HTTP/1.1 +Host: quack.duckity.com +Accept: application/json +Content-Type: application/json + +{} +``` + +In case you want to specify threat correlation keys, pass them in the object under `keys`, as +follows: + +```json +{ + "keys": { + "key1": "val1", + "key2": "val2" + } +} +``` + +The response on success will look like follows: + +```http +HTTP/1.1 200 OK +Content-Type: application/json +X-RateLimit-Next-In: 1000 +X-RateLimit-Resets-In: 1000 +X-RateLimit-Remaining: 0 +X-RateLimit-Penalty-Resets-In: 0 + +{ + "challenge": "" +} +``` + +### Solve a Challenge [step] + +Once you have a challenge string, use the following methods to solve a challenge: + +```rs +fn main() { + let original = String::from(""); + + let challenge = duckity_core::decode(&original).unwrap(); + let solution = duckity_core::solve(&challenge); + let solution = duckity_core::encode(&original, &solution).unwrap(); +} +``` + +`duckity_core::solve()` is CPU-intensive, take appropriate measures if it may block concurrent +processing (e.g. a UI thread). diff --git a/content/sdks/rust-std.mdx b/content/sdks/rust-std.mdx index b9a53a5..b64100d 100644 --- a/content/sdks/rust-std.mdx +++ b/content/sdks/rust-std.mdx @@ -1,4 +1,90 @@ --- title: Rust (STD) icon: SiRust ---- \ No newline at end of file +--- + +Welcome to the Rust (with STD) SDK documentation! As the name says, and unlike the no-STD SDK, this +SDK requires the standard library to compile. In exchange, it's about 3 times faster than the +no-STD SDK. + +## Quick Start + +Before you can integrate Duckity into your application, you'll need to have the following: + +1. An application, +2. At least one protection profile created in that application, and +3. The ID of the protection profile(s) to use + +If you're missing either of those, head over to the [Duckity Dashboard](https://app.duckity.com) or +read the [Quick Start](/quick-start) guide to learn how to set those up. + +Once you got those ready, follow these steps to get things running on your client: + +### Install the SDK [step] + +To install the SDK in your project, run the following command in your shell: + +```sh +cargo install duckity +``` + +You'll also need Tokio to use it (`reqwest` depends on it). + + + In case you cannot use Tokio, the `async-compat` crate may help. Using it is + untested, and out of scope for this documentation. You may also skip getting + challenges using the SDK and only use the `duckity` create to solve + manually-fetched challenges. + + +### Get and Solve a Challenge [step] + +Once you have `duckity` installed, you can start getting challenges with `duckity::get()`. + +```rs +const PROTECTION_PROFILE_ID: &'static str = ""; + +#[tokio::main] +async fn main() -> anyhow::Result<()> { + let challenge: String = duckity::get(PROTECTION_PROFILE_ID).await?; + let solution: String = tokio::task::spawn_blocking(move || duckity::solve(&challenge))??; + + println!("{solution}"); + + Ok(()) +} +``` + +Don't forget to run `duckity::solve()` in `tokio::task::spawn_blocking()`. Calling +`duckity::solve()` directly from your async context will block the runtime's thread until the call +is done. `tokio::task::spawn_blocking()` is available under the `rt` tokio feature. + +## Advanced Usage + +Threat correlation and self-hosted endpoints are also supported by this crate. + +### Threat Correlation Keys + +To specify threat correlation keys when getting a challenge, use `ChallengeGetter::key()`. For +example: + +```rs +let challenge = duckity::get(PROTECTION_PROFILE_ID) + .key("key1", key1) + .key("key2", key2) + .await?; +``` + +### Using On Self-Hosted Ducklings + +Self-hosted ducklings are hosted at a different domain from Duckity-hosted ducklings. To point it +to a custom domain, use `ChallengeGetter::base_url()`: + +```rs +let challenge = duckity::get(PROTECTION_PROFILE_ID) + .base_url("https://quack.duckity.com") // Without trailing slash + .await?; +``` + +The default value for the `api` parameter is `"https://quack.duckity.com"`, which points to +Duckity's hosted duckling. Change the domain name to your duckling's and you'll be ready to go.