Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
usox authored Mar 20, 2024
1 parent 9a901f1 commit 62bcf79
Showing 1 changed file with 1 addition and 102 deletions.
103 changes: 1 addition & 102 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,104 +1,3 @@
# hypersonic

[![Unittests](https://github.com/usox/hypersonic/actions/workflows/php.yml/badge.svg)](https://github.com/usox/hypersonic/actions/workflows/php.yml)
[![Code Coverage](https://scrutinizer-ci.com/g/usox/hypersonic/badges/coverage.png?b=main)](https://scrutinizer-ci.com/g/usox/hypersonic/?branch=main)
[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/usox/hypersonic/badges/quality-score.png?b=main)](https://scrutinizer-ci.com/g/usox/hypersonic/?branch=main)

Library for building APIs following the [subsonic](http://www.subsonic.org/) API definitions.

**Under heavy development; just a bunch of methods is supported at the moment**

## Usage

### Prerequisites

- PHP 8.1
- PSR compliant request-flow (e.g. using a framework like [Slim](https://www.slimframework.com/))
- Free `/rest/`-route in your application (sadly this can't be changed atm)

### Installation

```shell
composer require usox/hypersonic
```

### Initialization

Part of the initialization is the definition of all available API methods. Every method needs a class which implements the methods
DataProviderInterface. Those interfaces declare the format how the data needs to be build to be served using the API.

Also a AuthenticationProvider is needed to provide auth-mechanics for the API. See Authentication for further details.

```php
use Usox\HyperSonic\FeatureSet\V1161\FeatureSetFactory;

$hyperSonic = HyperSonic::init(
new FeatureSetFactory(),
new MyAuthenticationProvider(), // implements AuthenticationProviderInterface
[
'ping.view' => fn () => new MyPingClass(), // implements PingDataProviderInterface
'getLicense.view' => fn () => new MyLicenseClass(), // implements LicenseDataProviderInterface
'getArtists.view' => fn () => new MyArtistListClass(), // implements ArtistListDataProviderInterface
...
],
);


```

### API routing

Simply use the created Hypersonic as route handler for `/rest/*` routes - e.g. when using Slim:

```php
$app = AppFactory::create();
$app->get('/rest/{methodName}', $hyperSonic);
```

### Authentication

#### Warning

The subsonic protocol is somewhat sloppy when it comes to security.
Prior to version `1.13.0`, the protocol expects the username and the password to be sent as part of the query string -
the password itself is either transferred as plaintext or hex-encoded.

Starting with `1.13.0` the protocol added support for access-tokens - a md5 hash consisting of the password and a salt
(which also gets added to the query params).
Although md5 is considered a unsafe hashing-algo, it's way better than before. Sadly, some apps supporting the protocol still
use the old auth mechanism (or both).

Therefor, hypersonic also supports both ways, and I strongly recommend _not_ to use user passwords you store somewhere in
your server application for api authentication. Please consider using separate api-keys/tokens as user password just for the api. This way, you may
lower any security related impact in case of a security breach.

Also consider not to implement methods which may have access to sensible data and/or modify server data (e.g. starting a music folder scan).

#### Authentication Provider

The `AuthenticationProviderInterface` expects two methods to be implemented, one for the token auth and the second for username+password auth.

To check against the token, use the users api key (or the _plaintext_ user password for god’s sake), append the salt and md5-hash it.

### Protocol-Versions

Please see the official [subsonic api documentation](http://www.subsonic.org/pages/api.jsp) for details.

#### 1.16.1 - Currently supported methods

- getAlbum.view
- getAlbumList2.view
- getArtists.view
- getArtist.view
- getCoverArt.view
- getGenres.view
- getLicense.view
- getMusicFolders.view
- getRandomSongs.view
- getStarred2.view
- ping.view
- stream.view




Moved to codeberg https://codeberg.org/usox/hypersonic

0 comments on commit 62bcf79

Please sign in to comment.