view release on metacpan or  search on metacpan

lib/At/Protocol/Handle.pm  view on Meta::CPAN

    # All fatal errors
    register 'InvalidHandleError',     (), 1;
    register 'ReservedHandleError',    (), 1;
    register 'UnsupportedDomainError', (), 1;
    register 'DisallowedDomainError',  (), 1;
};
1;
__END__
=pod

=encoding utf-8

=head1 NAME

At::Protocol::Handle - AT Protocol Handle Validation

=head1 SYNOPSIS

    use At::Protocol::Handle qw[:all];
    try {
        ensureValidHandle( 'org.cpan.sanko' );
    }
    catch($err) {
        ...; # do something about it
    }


=head1 DESCRIPTION

L<DID|At::Protocol::DID>s are the long-term persistent identifiers for accounts in atproto, but they can be opaque and
unfriendly for human use. Handles are a less-permanent identifier for accounts. The mechanism for verifying the link
between an account handle and an account DID relies on DNS, and possibly connections to a network host, so every handle
must be a valid network hostname. I<Almost> every valid "hostname" is also a valid handle, though there are a small
number of exceptions.

This package aims to validate them.

=head1 Functions

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

=head2 C<new( ... )>

Verifies an id and creates a new object containing it.

    my $handle = At::Protocol::Handle->new( 'org.cpan.sanko' );

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

=head2 C<ensureValidHandle( ... )>

    ensureValidHandle( 'org.cpan.sanko' );

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

=head2 C<ensureValidHandleRegex( ... )>

    ensureValidHandleRegex( 'org.cpan.sanko' );

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

=head2 C<normalizeHandle( ... )>

    my $handle = ensureValidHandleRegex( 'org.cpan.SANKO' );

Normalizes a handle according to spec. ...honestly, it just makes sure it's lowercase.

=head2 C<normalizeAndEnsureValidHandle( ... )>

    my $handle = normalizeAndEnsureValidHandle( 'org.cpan.SANKO' );

Normalizes and validates an id. Throws errors on failure and returns the normalized id on success.

=head2 C<isValidHandle( ... )>

    my $ok = ensureValidHandle( 'org.cpan.sanko' );

Validates an id and catches any fatal errors. Returns a boolean value.

=head2 C<isValidTld( ... )>

    my $ok = isValidTld( 'cpan.org' );

Returns a boolean indicating whether the given TLD is valid for use as a handle according to the AT protocol spec.

=head1 See Also

L<https://atproto.com/specs/handle>

=head1 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.

=head1 AUTHOR

Sanko Robinson E<lt>sanko@cpan.orgE<gt>

=begin stopwords

atproto

=end stopwords

=cut