mackuba.eu
A library for handling DID identifiers used in Bluesky AT Protocol
updated readme
+56
-32
+56
-32
README.md
+56
-32
README.md
···
13
14
## Installation
15
16
gem install didkit
17
18
19
## Usage
20
21
-
Use the `DIDKit::Resolver` class to look up DIDs and handles.
22
-
23
-
To look up a handle:
24
25
```rb
26
-
resolver = DIDKit::Resolver.new
27
-
resolver.resolve_handle('nytimes.com')
28
-
# => #<DIDKit::DID:0x00000001035956b0 @did="did:plc:eclio37ymobqex2ncko63h4r", @type=:plc, @resolved_by=:dns>
29
```
30
31
-
This returns an object of `DIDKit::DID` class (aliased as just `DID`), which tells you:
32
33
- the DID as a string (`#to_s` or `#did`)
34
- the DID type (`#type`, `:plc` or `:web`)
35
- if the handle was resolved via a DNS entry or a `.well-known` file (`#resolved_by`, `:dns` or `:http`)
36
37
-
To go in the other direction – to find an assigned and verified handle given a DID – use `get_validated_handle` (pass DID as a string or an object):
38
39
```rb
40
-
resolver.get_validated_handle('did:plc:ewvi7nxzyoun6zhxrhs64oiz')
41
-
# => "atproto.com"
42
```
43
44
-
You can also load the DID document using `resolve_did`:
45
46
```rb
47
-
doc = resolver.resolve_did('did:plc:ragtjsm2j2vknwkz3zp4oxrd')
48
-
# => #<DIDKit::Document:0x0000000105d751f8 @did=#<DIDKit::DID:...>, @json={...}>
49
50
-
doc.handles
51
-
# => ["pfrazee.com"]
52
53
-
doc.pds_endpoint
54
-
# => "https://morel.us-east.host.bsky.network"
55
```
56
57
-
There are also some helper methods in the `DID` class that create a `Resolver` for you to save you some typing:
58
59
-
```rb
60
-
did = DID.resolve_handle('jay.bsky.team')
61
-
# => #<DIDKit::DID:0x000000010615ed28 @did="did:plc:oky5czdrnfjpqslsw2a5iclo", @type=:plc, @resolved_by=:dns>
62
63
-
did.to_s
64
-
# => "did:plc:oky5czdrnfjpqslsw2a5iclo"
65
66
-
did.get_document
67
-
# => #<DIDKit::Document:0x00000001066d4898 @did=#<DIDKit::DID:...>, @json={...}>
68
69
-
did.get_validated_handle
70
-
# => "jay.bsky.team"
71
```
72
-
73
74
### Configuration
75
76
-
You can override the nameserver used for DNS lookups by setting the `nameserver` property in `Resolver`, e.g. to use Google's or CloudFlare's global DNS:
77
78
-
```
79
-
resolver.nameserver = '8.8.8.8'
80
-
```
81
82
83
## Credits
84
···
13
14
## Installation
15
16
+
From the command line:
17
+
18
gem install didkit
19
+
20
+
Or, add this to your `Gemfile`:
21
+
22
+
gem 'didkit', '~> 0.3'
23
24
25
## Usage
26
27
+
The simplest way to use the gem is through the `DIDKit::DID` class, aliased as just `DID`:
28
29
```rb
30
+
did = DID.resolve_handle('jay.bsky.team')
31
+
# => #<DIDKit::DID:0x0... @did="did:plc:oky5czdrnfjpqslsw2a5iclo",
32
+
# @resolved_by=:dns, @type=:plc>
33
```
34
35
+
This returns a `DID` object, which tells you:
36
37
- the DID as a string (`#to_s` or `#did`)
38
- the DID type (`#type`, `:plc` or `:web`)
39
- if the handle was resolved via a DNS entry or a `.well-known` file (`#resolved_by`, `:dns` or `:http`)
40
41
+
To go in the other direction – to find an assigned and verified handle given a DID – create a `DID` from a DID string and call `get_verified_handle`:
42
43
```rb
44
+
DID.new('did:plc:ewvi7nxzyoun6zhxrhs64oiz').get_verified_handle
45
+
# => "atproto.com"
46
```
47
48
+
You can also load the DID JSON document using `#document`, which returns a `DIDKit::Document` (`DID` caches the document, so don't worry about calling this method multiple times):
49
50
```rb
51
+
did = DID.new('did:plc:ragtjsm2j2vknwkz3zp4oxrd')
52
53
+
did.document.handles
54
+
# => ["pfrazee.com"]
55
56
+
did.document.pds_host
57
+
# => "morel.us-east.host.bsky.network"
58
```
59
60
61
+
### Checking account status
62
63
+
`DIDKit::DID` also includes a few methods for checking the status of a given account (repo), which call the `com.atproto.sync.getRepoStatus` endpoint on the account's assigned PDS:
64
65
+
```rb
66
+
did = DID.new('did:plc:ch7azdejgddtlijyzurfdihn')
67
+
did.account_status
68
+
# => :takendown
69
+
did.account_active?
70
+
# => false
71
+
did.account_exists?
72
+
# => true
73
74
+
did = DID.new('did:plc:44ybard66vv44zksje25o7dz')
75
+
did.account_status
76
+
# => :active
77
+
did.account_active?
78
+
# => true
79
```
80
81
### Configuration
82
83
+
You can customize some things about the DID/handle lookups by using the `DIDKit::Resolver` class, which the methods in `DID` use behind the scenes.
84
85
+
Currently available options include:
86
+
87
+
- `:nameserver` - override the nameserver used for DNS lookups, e.g. to use Google's or CloudFlare's DNS
88
+
- `:timeout` - change the connection/response timeout for HTTP requests (default: 15 s)
89
+
- `:max_redirects` - change allowed maximum number of redirects (default: 5)
90
+
91
+
Example:
92
93
+
```rb
94
+
resolver = DIDKit::Resolver.new(nameserver: '8.8.8.8', timeout: 30)
95
+
96
+
did = resolver.resolve_handle('nytimes.com')
97
+
# => #<DIDKit::DID:0x0... @did="did:plc:eclio37ymobqex2ncko63h4r",
98
+
# @resolved_by=:dns, @type=:plc>
99
+
100
+
resolver.resolve_did(did)
101
+
# => #<DIDKit::Document:0x0... @did=#<DIDKit::DID:...>, @json={...}>
102
+
103
+
resolver.get_verified_handle(did)
104
+
# => 'nytimes.com'
105
+
```
106
107
## Credits
108