/ 
At-0.19
River stage one • 1 direct dependent • 1 total dependent
/ At::Protocol::URI

NAME

At::Protocol::URI - AT Protocol URI Validation

SYNOPSIS

use At::Protocol::URI qw[:all];
try {
    ensureValidNSID( 'net.users.bob.ping' );
}
catch($err) {
    ...; # do something about it
}

DESCRIPTION

The AT URI scheme (at://) makes it easy to reference individual records in a specific repository, identified by either DID or handle. AT URIs can also be used to reference a collection within a repository, or an entire repository (aka, an identity).

This package aims to validate them.

Functions

You may import functions by name or with the :all tag.

new( ... )

Verifies an AT-uri and creates a new object containing it.

my $uri = At::Protocol::URI->new( 'at://did:plc:44ybard66vv44zksje25o7dz/app.bsky.feed.post/3jwdwj2ctlk26' );

On success, an object is returned that will stringify to the URI itself.

create( ... )

my $uri_1 = create('did:plc:44ybard66vv44zksje25o7dz');
my $uri_2 = create('did:plc:44ybard66vv44zksje25o7dz', 'app.bsky.feed.post', '3jwdwj2ctlk26');
my $uri_3 = create('bnewbold.bsky.team', 'app.bsky.feed.post', '3jwdwj2ctlk26');

Allows you to build a new URI from parts.

Expected parameters include:

host - required

This is either a DID or handle.

collection
rkey

A new object is returned on success.

protocol( )

my $prot = $uri->protocol;

Returns the URI's protocol. This is always at:.

origin( )

my $base = $uri->origin;

Returns the protocol and host.

host( [...] )

my $host = $uri->host;
$uri->host('did:plc:...');

Mutator around the host.

pathname( [...] )

my $path = $uri->pathname;
$uri->pathname( '/foo' );

Mutator around the url path.

search( [...] )

my $search = $uri->search;
$uri->search( '?foo=bar' );

Mutator around the URI's search parameters.

hash( [...] )

my $hash = $uri->hash;
$uri->hash('hash');

Mutator around the URI's hash field.

When a strong reference to another record is required, best practice is to use a CID hash in addition to the AT URI.

collection( [...] )

my $collection = $uri->collection;
$uri->collection( 'app.bsky.feed.post' );

Mutator around the optional collection part of the path which must be a normalized NSID.

rkey( [...] )

my $rkey = $uri->rkey;
$uri->rkey( '3jzfcijpj2z2a' );

Mutator around the optional rkey of the path which must be a valid 'Record Key' according to the AT Protocol spec.

ensureValidAtUri( ... )

ensureValidAtUri( 'at://did:plc:asdf123' );

Validates an AT URI. Throws errors on failure and returns a true value on success.

ensureValidAtUriRegex( ... )

ensureValidAtUriRegex( 'a://did:plc:asdf123' ); # fatal

Validates an AT URI with cursory regex provided by the AT protocol designers. Throws errors on failure and returns a true value on success.

See Also

https://atproto.com/specs/at-uri-scheme

LICENSE

Copyright (C) Sanko Robinson.

This library is free software; you can redistribute it and/or modify it under the terms found in the Artistic License 2. Other copyrights, terms, and conditions may apply to data transmitted through this module.

AUTHOR

Sanko Robinson <sanko@cpan.org>