view release on metacpan or  search on metacpan

lib/Mojo/Transmission.pm  view on Meta::CPAN

      $self->{session_id} = $tx->res->headers->header('X-Transmission-Session-Id');
      return $self->ua->post_p($self->url, $self->_headers, json => $req);
    })->then(sub {
      return $_[0] if ref $_[0] eq 'HASH';    # _done() is already called
      my $tx = shift;
      warn '[TRANSMISSION] >>> ', dumper($tx->res->json || $tx->res->error), "\n" if DEBUG;
      return $self->_done($cb, _res($tx));
    });

    return $cb eq RETURN_PROMISE ? $p : $self;
  }

  # Blocking
  else {
    warn '[TRANSMISSION] <<< ', dumper($req), "\n" if DEBUG;
    my $tx = $self->ua->post($self->url, $self->_headers, json => $req);
    warn '[TRANSMISSION] >>> ', dumper($tx->res->json || $tx->res->error), "\n" if DEBUG;
    return _res($tx) unless ($tx->res->code // 0) == 409;
    $self->{session_id} = $tx->res->headers->header('X-Transmission-Session-Id');
    $tx = $self->ua->post($self->url, $self->_headers, json => $req);
    warn '[TRANSMISSION] >>> ', dumper($tx->res->json || $tx->res->error), "\n" if DEBUG;
    return _res($tx);
  }
}

sub _headers {
  my $self = shift;
  return {'X-Transmission-Session-Id' => $self->{session_id} || ''};
}

sub _res {
  my $res = $_[0]->res->json || {error => $_[0]->res->error};
  $res->{error} ||= $res->{result};
  return $res if !$res->{result} or $res->{result} ne 'success';
  return $res->{arguments};
}

my @TR_STATUS = qw(stopped check_wait check download_wait download seed_wait seed);
sub tr_status { defined $_[0] && $_[0] >= 0 && $_[0] <= @TR_STATUS ? $TR_STATUS[$_[0]] : '' }

1;

=encoding utf8

=head1 NAME

Mojo::Transmission - Client for talking with Transmission BitTorrent daemon

=head1 DESCRIPTION

L<Mojo::Transmission> is a very lightweight client for exchanging data with
the Transmission BitTorrent daemon using RPC.

The documentation in this module might seem sparse, but that is because the API
is completely transparent regarding the data-structure received from the
L<Transmission API|https://trac.transmissionbt.com/browser/trunk/extras/rpc-spec.txt>.

=head1 SYNOPSIS

  my $transmission = Mojo::Transmission->new;
  $transmission->add(url => "http://releases.ubuntu.com/17.10/ubuntu-17.10.1-desktop-amd64.iso.torrent");

  my $torrents = $transmission->torrent([]);
  $transmission->torrent(remove => $torrents[0]->{id}) if @$torrents;

=head1 ATTRIBUTES

=head2 default_trackers

  $array_ref    = $transmission->default_trackers;
  $transmission = $transmission->default_trackers([$url, ...]);

Holds a list of default trackers that can be used by L</add>.

=head2 ua

  $ua           = $transmission->ua;
  $transmission = $transmission->ua(Mojo::UserAgent->new);

Holds a L<Mojo::UserAgent> used to issue requests to backend.

=head2 url

  $url          = $transmission->url;
  $transmission = $transmission->url(Mojo::URL->new);

L<Mojo::URL> object holding the URL to the transmission daemon.
Default to the C<TRANSMISSION_RPC_URL> environment variable or
"http://localhost:9091/transmission/rpc".

=head1 METHODS

=head2 add

  # Generic call
  $res          = $transmission->add(\%args);
  $transmission = $transmission->add(\%args, sub { my ($transmission, $res) = @_ });

  # magnet:?xt=${xt}&dn=${dn}&tr=${tr}
  $transmission->add({xt => "...", dn => "...", tr => [...]});

  # magnet:?xt=urn:btih:${hash}&dn=${dn}&tr=${tr}
  $transmission->add({hash => "...", dn => "...", tr => [...]});

  # Custom URL or file
  $transmission->add({url => "...", tr => [...]});

This method can be used to add a torrent. C<tr> defaults to L</default_trackers>.

See also L<https://trac.transmissionbt.com/browser/trunk/extras/rpc-spec.txt#L356>.

=head2 add_p

  $promise = $transmission->add_p(\%args);

Same as L</add>, but returns a promise.

=head2 session

  # session-get
  $transmission = $transmission->session([], sub { my ($transmission, $res) = @_; });