# doc

## Overview

Plugin should be bundled as an apk. `$PLUGIN_ID` in this documentation corresponds to the executable name for the plugin in order to be cross-platform, e.g. `obfs-local`. An apk can have more than one plugins bundled. We don't care as long as they have different `$PLUGIN_ID`. For duplicated plugin ID, host should refuse to start.

There are no arbitrary restrictions/requirements on package name, component name and content provider authority, but you're suggested to follow the format in this documentations. For package name, use `com.github.shadowsocks.plugin.$PLUGIN_ID` if it only contains a single plugin to prevent duplicated plugins. In some places hyphens are not accepted, for example package name. In that case, hyphens `-` should be changed into underscores `_`. For example, the package name for `obfs-local` would probably be `com.github.shadowsocks.plugin.obfs_local`.

It's advised to use this library for easier development, but you're free to start from scratch following this documentation.

## Plugin configuration

Plugins get their args configured via one of the following two options:

* A configuration activity;

  ([example](https://github.com/shadowsocks/simple-obfs-android/tree/4f82c4a4e415d666e70a7e2e60955cb0d85c1615))
* If no configuration activity is found or the activity requests the fallback mode, the fallback

  mode will be used: user manual input and optional help message.

  ([example](https://github.com/shadowsocks/kcptun-android/tree/41f42077e177618553417c16559784a51e9d8c4c))

Your user interface need not be consistent with shadowsocks-android styling - you don't need to use preferences UI at all if you don't feel like it - however it's recommended to use Material Design at minimum.

### Configuration activity

If the plugin provides a configuration activity, it will be started when user picks your plugin and taps configure. It:

* MUST have action: `com.github.shadowsocks.plugin.ACTION_CONFIGURE`;
* MUST have category: `android.intent.category.DEFAULT`;
* MUST be able to receive data URI `plugin://com.github.shadowsocks/$PLUGIN_ID`;
* SHOULD parse string extra `com.github.shadowsocks.plugin.EXTRA_OPTIONS` (all options as a single

  string) and display the current options;
* SHOULD distinguish between server settings and feature settings in some way, e.g. for

  `obfs-local`, `obfs` is a server setting and `obfs_host` is a feature setting;
* On finish, it SHOULD return one of the following results:
  * `RESULT_OK = 0`: In this case it MUST return the data Intent with the new

    `com.github.shadowsocks.plugin.EXTRA_OPTIONS`;
  * `RESULT_CANCELED = -1`: Nothing will be changed;
  * `RESULT_FALLBACK = 1`: Fallback mode is requested and the host should display the fallback

    editor.

This corresponds to `com.github.shadowsocks.plugin.ConfigurationActivity` in the plugin library. Here's what a proper configuration activity usually should look like in `AndroidManifest.xml`:

```markup
<manifest>
    ...
    <application>
        ...
        <activity android:name=".ConfigActivity">
            <intent-filter>
                <action android:name="com.github.shadowsocks.plugin.ACTION_CONFIGURE"/>
                <category android:name="android.intent.category.DEFAULT"/>
                <data android:scheme="plugin"
                      android:host="com.github.shadowsocks"
                      android:path="/$PLUGIN_ID"/>
            </intent-filter>
        </activity>
        ...
    </application>
</manifest>
```

### Help activity/callback

If the plugin doesn't provide a configuration activity, it's highly recommended to provide a help message in the form of an Activity. It:

* MUST have action: `com.github.shadowsocks.plugin.ACTION_HELP`;
* MUST have category: `android.intent.category.DEFAULT`;
* MUST be able to receive data URI `plugin://com.github.shadowsocks/$PLUGIN_ID`;
* CAN parse string extra `com.github.shadowsocks.plugin.EXTRA_OPTIONS` and display some more

  relevant information;
* SHOULD parse `@NightMode` int extra `com.github.shadowsocks.plugin.EXTRA_NIGHT_MODE` and act

  accordingly;
* SHOULD either:
  * Be invisible and return help message with CharSequence extra

    `com.github.shadowsocks.plugin.EXTRA_HELP_MESSAGE` in the data intent with `RESULT_OK`; (in this

    case, a simple dialog will be shown containing the message)
  * Be visible and return `RESULT_CANCELED`.
* SHOULD distinguish between server settings and feature settings in some way, e.g. for

  `simple_obfs`, `obfs` is a server setting and `obfs_host` is a feature setting.

This corresponds to `com.github.shadowsocks.plugin.HelpActivity` or `com.github.shadowsocks.plugin.HelpCallback` in the plugin library. Here's what a proper help activity/callback usually should look like in `AndroidManifest.xml`:

```markup
<manifest>
    ...
    <application>
        ...
        <activity android:name=".HelpActivity">
            <intent-filter>
                <action android:name="com.github.shadowsocks.plugin.ACTION_HELP"/>
                <category android:name="android.intent.category.DEFAULT"/>
                <data android:scheme="plugin"
                      android:host="com.github.shadowsocks"
                      android:path="/$PLUGIN_ID"/>
            </intent-filter>
        </activity>
        ...
    </application>
</manifest>
```

## Plugin implementation

Every plugin can be either in native mode or JVM mode.

### Native mode

In native mode, plugins are provided as native executables and `shadowsocks-libev`'s plugin mode will be used.

Every native mode plugin MUST have a content provider to provide the native executables (since they can exceed 1M which is the limit of Intent size) that:

* MUST have `android:label` and `android:icon`; (may be inherited from parent `application`)
* SHOULD have `android:directBootAware="true"` with proper support if possible;
* MUST have an intent filter with action `com.github.shadowsocks.plugin.ACTION_NATIVE_PLUGIN`;

  (used for discovering plugins)
* MUST have meta-data `com.github.shadowsocks.plugin.id` with string value `$PLUGIN_ID` or a string resource;
* MUST have an intent filter with action `com.github.shadowsocks.plugin.ACTION_NATIVE_PLUGIN` and

  data `plugin://com.github.shadowsocks/$PLUGIN_ID`; (used for configuring plugin)
* CAN have meta-data `com.github.shadowsocks.plugin.default_config` with string value or a string resource, default is empty;
* MUST implement `query` that returns the file list which MUST include `$PLUGIN_ID` when having

  these as arguments:

  * `uri = "content://$authority_of_your_provider`;
  * `projection = ["path", "mode"]`; (relative path, for example `obfs-local`; file mode as integer, for

    example `0b110100100`)
  * `selection = null`;
  * `selectionArgs = null`;
  * `sortOrder = null`;
* MUST implement `openFile` that for files returned in `query`, `openFile` with `mode = "r"` returns

  a valid `ParcelFileDescriptor` for reading. For example, `uri` can be

  `content://com.github.shadowsocks.plugin.kcptun/kcptun`.

This corresponds to `com.github.shadowsocks.plugin.NativePluginProvider` in the plugin library. Here's what a proper native plugin provider usually should look like in `AndroidManifest.xml`:

```markup
<manifest>
    ...
    <application>
        ...
        <provider android:name=".BinaryProvider"
                  android:exported="true"
                  android:directBootAware="true"
                  android:authorities="$FULLY_QUALIFIED_NAME_OF_YOUR_CONTENTPROVIDER"
                  tools:ignore="ExportedContentProvider">
            <intent-filter>
                <action android:name="com.github.shadowsocks.plugin.ACTION_NATIVE_PLUGIN"/>
            </intent-filter>
            <intent-filter>
                <action android:name="com.github.shadowsocks.plugin.ACTION_NATIVE_PLUGIN"/>
                <data android:scheme="plugin"
                      android:host="com.github.shadowsocks"
                      android:path="/$PLUGIN_ID"/>
            </intent-filter>
            <meta-data android:name="com.github.shadowsocks.plugin.id"
                       android:value="$PLUGIN_ID"/>
            <meta-data android:name="com.github.shadowsocks.plugin.default_config"
                       android:value="dummy=default;plugin=options"/>
        </provider>
        ...
    </application>
</manifest>
```

### Native mode without binary copying

If your plugin binary executable can run in place, you can support native mode without binary copying. To support this mode, your `ContentProvider` must first support native mode with binary copying (this will be used if the fast routine fails) and:

* MUST implement `call` that returns absolute path to the entry executable as

  `com.github.shadowsocks.plugin.EXTRA_ENTRY` when having `method = "shadowsocks:getExecutable"`;

  (`com.github.shadowsocks.plugin.EXTRA_OPTIONS` is provided in extras as well just in case you

  need them)
* SHOULD define `android:installLocation="internalOnly"` for `<manifest>` in AndroidManifest.xml;
* SHOULD define `android:extractNativeLibs="true"` for `<application>` in AndroidManifest.xml;

If you don't plan to support this mode, you can just throw `UnsupportedOperationException` when being invoked. It will fallback to the slow routine automatically.

#### Native mode without binary copying and setup

Additionally, if your plugin only needs to supply the path of your executable without doing any extra setup work, you can use an additional `meta-data` with name `com.github.shadowsocks.plugin.executable_path` to supply executable path to your native binary. This allows the host app to launch your plugin without ever launching your app.

### JVM mode

This feature hasn't been implemented yet. Please open an issue if you need this.

## Plugin security

Plugins are certified using package signatures and shadowsocks-android will consider these signatures as trusted:

* Signatures by [trusted sources](https://github.com/bannedbook/fanqiang/tree/ba8196b1d5aa078445c3e8fa6a93513875688c1e/mobile/src/main/java/com/github/shadowsocks/plugin/PluginManager.kt#L39)

  which includes:

  * @madeye, i.e. the signer of the main repo;
  * The main repo doesn't contain any other trusted signatures. Third-party forks should add their

    signatures to this trusted sources if they have plugins signed by them before publishing their

    source code.
* Current package signature, which means:
  * If you get apk from shadowsocks-android releases or Google Play, this means only apk signed by

    @madeye will be recognized as trusted.
  * If you get apk from a third-party fork, all plugins from that developer will get recognized as

    trusted automatically even if its source code isn't available anywhere online.

A warning will be shown for untrusted plugins. No arbitrary restrictions will be applied.

## Plugin platform versioning

In order to be able to identify compatible and incompatible plugins, [Semantic Versioning](http://semver.org/) will be used.

> Given a version number MAJOR.MINOR.PATCH, increment the:
>
> 1. MAJOR version when you make incompatible API changes,
> 2. MINOR version when you add functionality in a backwards-compatible manner, and
> 3. PATCH version when you make backwards-compatible bug fixes.

Plugin app must include this in their application tag: (which should be automatically included if you are using our library)

```
<meta-data android:name="com.github.shadowsocks.plugin.version"
           android:value="1.0.0"/>
```

## Plugin ID Aliasing

To implement plugin ID aliasing, you:

* MUST define meta-data `com.github.shadowsocks.plugin.id.aliases` in your plugin content provider with `android:value="alias"`,

  or use `android:resources` to specify a string resource or string array resource for multiple aliases.
* MUST be able to be matched by `com.github.shadowsocks.plugin.ACTION_NATIVE_PLUGIN` when invoked on alias.

  To do this, you SHOULD use multiple `intent-filter` and use a different `android:path` for each alias.

  Alternatively, you MAY also use a single `intent-filter` and use `android:pathPattern` to match all your aliases at once.

  You MUST NOT use `android:pathPrefix` or allow `android:pathPattern` to match undeclared plugin ID/alias as it might create a conflict with other plugins.
* SHOULD NOT add or change `intent-filter` for activities to include your aliases -- your plugin ID will always be used.

For example:

```markup
<manifest>
    ...
    <application>
        ...
        <provider>
            ...
            <intent-filter>
                <action android:name="com.github.shadowsocks.plugin.ACTION_NATIVE_PLUGIN"/>
                <data android:scheme="plugin"
                      android:host="com.github.shadowsocks"
                      android:path="/$PLUGIN_ID"/>
            </intent-filter>
            <intent-filter>
                <action android:name="com.github.shadowsocks.plugin.ACTION_NATIVE_PLUGIN"/>
                <data android:scheme="plugin"
                      android:host="com.github.shadowsocks"
                      android:path="/$PLUGIN_ALIAS"/>
            </intent-filter>
            <meta-data android:name="com.github.shadowsocks.plugin.id"
                       android:value="$PLUGIN_ID"/>
            <meta-data android:name="com.github.shadowsocks.plugin.aliases"
                       android:value="$PLUGIN_ALIAS"/>
            ...
        </provider>
        ...
    </application>
</manifest>
```

## Android TV

Android TV client does not invoke configuration activities. Therefore your plugins should automatically work with them.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://fanqiang.gitbook.io/fanqiang/fqnews/plugin/doc.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.