File Coverage

lib/OAuthomatic/OAuthInteraction.pm
Criterion Covered Total %
statement 1 3 33.3
branch n/a
condition n/a
subroutine 1 1 100.0
pod n/a
total 2 4 50.0


line stmt bran cond sub pod time code
1             package OAuthomatic::OAuthInteraction;
2             # ABSTRACT: handle browser redirects happening during OAuth initial exchange
3              
4 1     1   856 use Moose::Role;
  0            
  0            
5             use OAuthomatic::Types;
6             use namespace::sweep;
7              
8              
9              
10              
11             requires 'callback_url';
12              
13              
14             requires 'wait_for_oauth_grant';
15              
16              
17             requires 'prepare_to_work';
18              
19              
20             requires 'cleanup_after_work';
21              
22              
23              
24             1;
25              
26             __END__
27              
28             =pod
29              
30             =encoding UTF-8
31              
32             =head1 NAME
33              
34             OAuthomatic::OAuthInteraction - handle browser redirects happening during OAuth initial exchange
35              
36             =head1 VERSION
37              
38             version 0.01
39              
40             =head1 SYNOPSIS
41              
42             $oauth_interaction->prepare_to_work();
43             say "Spawn browser on ", $oauth_interaction->callback_url;
44             my $app_cred = $oauth_interaction->wait_for_oauth_grant();
45             $oauth_interaction->cleanup_after_work();
46              
47             =head1 DESCRIPTION
48              
49             APIs required from module responsible for receiving completion of
50             access-granting interaction with the OAuth-protected site.
51              
52             Main problem resolved here is that OAuth authorization is completed by
53             browser redirect, with tokens crucial for the process provided in
54             URL. This module is about receiving this redirect and extracting this
55             info.
56              
57             Default implementation - L<OAuthomatic::OAuthInteraction::ViaMicroWeb>
58             - spawns embedded temporary webserver on local address.
59              
60             =head1 METHODS
61              
62             =head2 callback_url()
63              
64             Which url should be given to access-granting website as URL
65             for final callback.
66              
67             It may be localhost address (it suffices that it works in local
68             browser, need not be reachable from internet).
69              
70             In extreme case some fake address can be used and user instructed to
71             copy and paste it to the application when prompted.
72              
73             =head2 wait_for_oauth_grant() => Verifier(...)
74              
75             Wait until callback is received, extract and return obtained
76             tokens. Return undef in case obtained results are invalid.
77              
78             =head2 prepare_to_work()
79              
80             Prepare and start anything necessary to handle other calls (in
81             particular, to receive call to L</callback url>).
82              
83             Example implementation starts separate thread with temporary webserver.
84              
85             =head2 cleanup_after_work()
86              
87             Called once object is no longer needed, may cleanup whatever
88             L</prepare_to_work> initialized or started.
89              
90             =head1 AUTHOR
91              
92             Marcin Kasperski <Marcin.Kasperski@mekk.waw.pl>
93              
94             =head1 COPYRIGHT AND LICENSE
95              
96             This software is copyright (c) 2015 by Marcin Kasperski.
97              
98             This is free software; you can redistribute it and/or modify it under
99             the same terms as the Perl 5 programming language system itself.
100              
101             =cut