@baptistecdr/aria2
Version:
Library for aria2, "The next generation download utility."
259 lines (191 loc) • 6.58 kB
Markdown
# aria2.js
JavaScript (Node.js and browsers) library
for [aria2, "The next generation download utility."](https://aria2.github.io/).
## Introduction
aria2.js controls aria2 via its [JSON-RPC interface](https://aria2.github.io/manual/en/html/aria2c.html#rpc-interface)
and features:
- Node.js and browsers support
- multiple transports
- [HTTP](https://aria2.github.io/manual/en/html/aria2c.html#rpc-interface)
- [WebSocket](https://aria2.github.io/manual/en/html/aria2c.html#json-rpc-over-websocket)
- promise API
- no 3rd party dependency
See [aria2 methods](https://aria2.github.io/manual/en/html/aria2c.html#methods)
and [aria2 notifications](https://aria2.github.io/manual/en/html/aria2c.html#notifications).
## Getting started
Start aria2 with rpc, example:
`aria2c --enable-rpc --rpc-listen-all=true --rpc-allow-origin-all`
```sh
npm install @baptistecdr/aria2
```
### Browser
```javascript
import Aria2 from '@baptistecdr/aria2/dist/esm-browser/bundle.js';
const serverOptions = {
"host": "localhost",
"port": 6800,
"secure": true,
"secret": "",
"path": "/jsonrpc",
};
const aria2 = new Aria2(serverOptions);
```
See [main.html](examples/browser/index.html) for a complete example.
### Node.js
```javascript
import Aria2 from "@baptistecdr/aria2";
const serverOptions = {
host: "localhost",
port: 6800,
secure: false,
secret: "",
path: "/jsonrpc",
};
const aria2 = new Aria2(serverOptions);
```
See [main.js](examples/node/main.js) for a complete example.
```shell
node examples/node/main.js
```
## Usage
Default options match aria2c defaults and are
```json
{
"host": "localhost",
"port": 6800,
"secure": false,
"secret": "",
"path": "/jsonrpc"
}
```
`secret` is optional and refers
to [--rpc-secret](https://aria2.github.io/manual/en/html/aria2c.html#cmdoption--rpc-secret). If you define it, it will
be added to every call for you.
If the WebSocket is open (via the [open method](#open)) aria2.js will use the WebSocket transport, otherwise the HTTP
transport.
The `"aria2."` prefix can be omitted from both methods and notifications.
### open
`aria2.open()` opens the WebSocket connection. All subsequent requests will use the WebSocket transport instead of HTTP.
```javascript
await aria2.open();
console.log("open");
```
### close
`aria2.close()` closes the WebSocket connection. All subsequent requests will use the HTTP transport instead of
WebSocket.
```javascript
await aria2.close();
console.log("closed");
```
### call
`aria2.call()` calls a method. Parameters are provided as arguments.
Example using [`addUri`](https://aria2.github.io/manual/en/html/aria2c.html#aria2.addUri) method to download from a
magnet link.
```javascript
const magnet =
"magnet:?xt=urn:btih:88594AAACBDE40EF3E2510C47374EC0AA396C08E&dn=bbb_sunflower_1080p_30fps_normal.mp4&tr=udp%3a%2f%2ftracker.openbittorrent.com%3a80%2fannounce&tr=udp%3a%2f%2ftracker.publicbt.com%3a80%2fannounce&ws=http%3a%2f%2fdistribution.bbb3d.renderfarming.net%2fvideo%2fmp4%2fbbb_sunflower_1080p_30fps_normal.mp4";
const guid = await aria2.call("addUri", [magnet], {dir: "/tmp"});
```
### multicall
`aria2.multicall()` is a helper
for [system.multicall](https://aria2.github.io/manual/en/html/aria2c.html#system.multicall). It returns an array of
results or throw if any of the call failed.
```javascript
const multicall = [
[methodA, param1, param2],
[methodB, param1, param2],
];
const results = await aria2.multicall(multicall);
```
### batch
`aria2.batch()` is a helper for [batch](https://www.jsonrpc.org/specification#batch). It behaves the same
as [multicall](#multicall) except it returns an array of promises which gives more flexibility in handling errors.
```javascript
const batch = [
[methodA, param1, param2],
[methodB, param1, param2],
];
const promises = await aria2.batch(batch);
```
### listNotifications
`aria2.listNotifications()` is a helper
for [system.listNotifications](https://aria2.github.io/manual/en/html/aria2c.html#system.listNotifications). The
difference with `aria2.call('listNotifications')` is that it removes the `"aria2."` prefix from the results.
```javascript
const notifications = await aria2.listNotifications();
/*
[
'onDownloadStart',
'onDownloadPause',
'onDownloadStop',
'onDownloadComplete',
'onDownloadError',
'onBtDownloadComplete'
]
*/
// notifications logger example
notifications.forEach((notification) => {
aria2.addEventListener(notification, ({detail}) => {
console.log("aria2", notification, detail);
});
});
```
### listMethods
`aria2.listMethods()` is a helper
for [system.listMethods](https://aria2.github.io/manual/en/html/aria2c.html#system.listMethods). The difference with
`aria2.call('listMethods')` is that it removes the `"aria2."` prefix for the results.
```javascript
const methods = await aria2.listMethods();
/*
[ 'addUri',
[...]
'system.listNotifications' ]
*/
```
### events
```javascript
// emitted when the WebSocket is open.
aria2.addEventListener("open", () => {
console.log("aria2", "OPEN");
});
// emitted when the WebSocket is closed.
aria2.addEventListener("close", () => {
console.log("aria2", "CLOSE");
});
// emitted when error occur.
aria2.addEventListener("error", ({error}) => {
console.error("aria2", "error", error);
});
// emitted for every data sent.
aria2.addEventListener("input", ({data}) => {
console.log("aria2", "IN");
console.dir(data);
});
// emitted for every data received.
aria2.addEventListener("output", ({data}) => {
console.log("aria2", "OUT");
console.dir(data);
});
// emitted for every notification received.
aria2.addEventListener("notification", ({method, params}) => {
console.log("aria2", "notification", {method, params});
});
```
Additionally, every [aria2 notifications](https://aria2.github.io/manual/en/html/aria2c.html#notifications) is also
emitted as an event. Only available when using WebSocket, see [open](#open).
```javascript
aria2.addEventListener("onDownloadStart", ({params: [guid]}) => {
console.log("aria2 onDownloadStart", guid);
});
```
## How to build
- Install [Node.JS LTS](https://nodejs.org/)
- Clone the project
- Run `npm install`
- Run `npm run test`
- Run `npm run build`
## Bugs and feature requests
Have a bug or a feature request? Please first search for existing and closed issues. If your problem or idea is not
addressed yet, [please open a new issue](https://github.com/baptistecdr/aria2.js/issues/new).
## Contributing
Contributions are welcome!