Crate pin

pin – a crate for managing your Pinboard links

Introduction

pin is a crate for working with Pinboard and, optionally, Instapaper. For instance, to send a link to Pinboard:

use pin::pinboard::{Client, Post, Tag, Title};
use reqwest::Url;
use std::str::FromStr;
let client = Client::new("https://api.pinboard.in", "jdoe:DECADE90C0DEDDABB1ED").unwrap();
let post = Post::new(Url::parse("http://foo.com").unwrap(),
                     Title::new("The Frobinator").unwrap(),
                     vec!["tag1", "tag2", "tag3"].iter().map(|s| Tag::from_str(s).unwrap()),
                     true);
client.send_post(&post).await.expect_err("Surely no one has that username & token?");

It is a small crate I wrote primarily to support my own workflow, and currently is used in the implementation of the pin CLI tool.

Retries & Backoff

Both the Pinboard & Instapaper APIs reserve the right to rate-limit callers. In the case of Pinboard, the advertised acceptable rate for most endpoints is one request every three seconds (much worse for a few selected endpoints), but I’ve seen far better than that in the wild. The docs suggest: “Make sure your API clients check for 429 Too Many Requests server errors and back off appropriately. If possible, keep doubling the interval between requests until you stop receiving errors.”

Instapaper is a bit more coy, only alluding to rate-limiting in their documentation for a 400 response code as being returned for “a bad request or exceeded the rate limit”. The rate limit is never defined, and I have never encountered it in the wild.

Regardless, you can use make_requests_with_backoff to make one or more requests with retries and (linear) backoff.

Modules

config

pin configuration items.

instapaper

Saving links to Instapaper.

pinboard

Managing Pinboard links

url_stream

Produce a Stream of Urls.

vars

Structs

InstapaperPost

Post a link to the Instapaper API

PinboardPost

Post to the Pinboard API, and optionally the Instapaper API

Enums

Error

SendError

Sender implementations can fail in one of two ways: we were rate-limited or “something else went wrong”

Traits

Sender

An entity that can send a single request with two failure modes: rate-limited, and everything else

Functions

get_tags

Get all Pinboard.in tags & pretty-print ’em

make_requests_with_backoff

Make a series of requests to an API, with retries & linear backoff.

Type Aliases

Result