jens/flipper
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Write up FlipperClient API.

Browse Source 
Summary:
Specifies the API for implementing your own Flipper Client.
I believe this provides everything you need to know to build a flipper-compliant client.
The only snag is that the current certificate exchange procedure would require a change to allow for new OS's, device types etc. It would be much better if we had a TLS-opt out so you don't need to go through all that rigmarole.

Reviewed By: passy

Differential Revision: D15150550

fbshipit-source-id: 2878dcc174807c3f86c0562660e8a3e43e5777b1
This commit is contained in:
John Knox
2019-05-01 04:07:39 -07:00
committed by Facebook Github Bot
parent 563d23a514
commit 56b85dd6e3
4 changed files with 303 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

44
docs/extending/establishing-a-connection.md
View File

@@ -1,9 +1,11 @@
---
id: establishing-a-connection
title: Establishing a connection
title: Secure Communication
---
Below is an outline of how a connection is established between an app with with our SDK integrated, and the desktop app. This all goes on behind the scenes inside the mobile SDK, so users shouldn't need to worry about it.
Below is an outline of how a connection is established between an app with our SDK integrated, and the desktop app. This all goes on behind the scenes inside the mobile SDK, so users shouldn't need to worry about it.
The connection process is a little more involved than you might expect, to stop Flipper clients on mobile apps from connecting to any server that happens to be running on localhost and potentially leaking information from your app.
## Transport Protocol
@@ -12,20 +14,50 @@ Flipper uses [RSocket](http://rsocket.io/) to communicate between the desktop an
## Client-Server relationship
When the desktop app starts up, it opens a secure socket on port 8088.
Any mobile app with the Flipper SDK installed will continually attempt to connect to this port on localhost to establish a connection with the desktop app.
The Flipper client will continually attempt to connect to this port on localhost to establish a connection with the desktop app.
## Certificate Exchange
To avoid mobile apps from connecting to untrusted ports on localhost, they will only connect to servers that have a valid, trusted TLS certificate.
To avoid mobile apps from connecting to untrusted ports on localhost, a Flipper client should only connect to servers that have a valid, trusted TLS certificate.
In order for the mobile app to know which certificates it can trust, it conducts a certificate exchange with the desktop app before it can make its first secure connection.
This is achieved through the following steps:
* Desktop app starts an insecure server on port 8089.
* Mobile app connects to localhost:8089 and sends a Certificate Signing Request to the desktop app.
* Desktop app uses it's private key (this is generated once and stored in ~/.flipper) to sign a client certificate for the mobile app.
* The desktop uses ADB (for android), or the mounted file system (for iOS simulators) to write the following files to the mobile app's private data partition
* The desktop uses ADB (for Android), or the mounted file system (for iOS simulators) to write the following files to the mobile app's private data partition
* Server certificate that the mobile app can now trust.
* Client certificate for the mobile app to use going forward.
* Now the mobile app knows which server certificate it can trust, and can connect to the secure server.
This allows the mobile app to trust a certificate if and only if, it is stored inside it's internal data partition. Typically it's only possible to write there with physical access to the device (i.e. through ADB or a mounted simulator).
This allows the mobile app to trust a certificate if and only if, it is stored inside its internal data partition. Typically it's only possible to write there with physical access to the device (i.e. through ADB or a mounted simulator).
To get the desktop app to generate a client certificate for your client, and then deploy it, go through the following steps:
Use an RSocket client to connect (insecurely) to the following URL:
(Parameters are defined in [Implementing a Flipper Client](new-clients))
```
localhost:8089/sonar?os={OS}
&device={DEVICE}
&app={APP}
&sdk_version={SDK_VERSION}
```
On that connection, send the following payload:
```
Request = {
"method": "signCertificate",
"csr": string,
"destination": string
}
```
Where `csr` is a Certificate Signing Request the client has generated, and `destination` identifies a location accessible to both the client and Flipper desktop, where the certificate should be placed.
The Subject Common Name (CN=...) must be included in the CSR, and your `CertificateProvider` implementation in Flipper may use this in combination with the `destination` to determine where to put the certificate.
This will ask Flipper desktop to generate a client certificate, using the CSR provided, and put it into the specified `destination`.
Depending on the client, `destination` can have a different meaning. A basic example would be a file path, that both the desktop and the client have access to. With this Flipper desktop could write the certificate to that path. A more involved example is that of the Android Client, where destination specifies a relative path inside an app container. And the Subject Common Name determines which app container. Together these two pieces of information form an absolute file path inside an android device.
For Flipper desktop to work with a given Client type, it needs to be modified to know how to correctly interpret the `destination` argument, and deploy certificates to it. You can see the current implementations in [CertificateProvider.js](https://github.com/facebook/flipper/blob/master/src/utils/CertificateProvider.js).

255
docs/extending/new-clients.md Normal file
View File

@@ -0,0 +1,255 @@
---
id: new-clients
title: Implementing a Flipper Client
---
In the GitHub repo, you'll find Flipper clients for Android, iOS and C++ code, but there's nothing to stop you from writing a FlipperClient for another device or OS.
Flipper clients communicate with the Flipper desktop app using JSON RPC messages over an [RSocket](http://rsocket.io/) connection.
This page documents the API, and you can use [FlipperConnectionManagerImpl.cpp](https://github.com/facebook/flipper/blob/master/xplat/Flipper/FlipperConnectionManagerImpl.cpp) for reference.
## Establishing a connection
Start by connecting to the Flipper server running within the desktop app. Connecting to the server registers your application with Flipper and enables plugins to interact with it. As the Flipper desktop has a different lifecycle than your app and may connect and disconnect at any time it is important that you attempt to reconnect to the Flipper server until it accepts your connection.
We use the RSocket protocol for communication between desktop and client, because it allows for easy certificate pinning and functionality like request-response messages.
In order to securely connect to Flipper, your client should first [obtain a certificate](establishing-a-connection).
After the client certificate has been obtained, connect to the following URL with an RSocket client:
```
localhost:8088/sonar?os={OS}
&device={DEVICE}
&device_id={DEVICE_ID}
&app={APP}
&sdk_version={SDK_VERSION}
&foreground={FOREGROUND}
```
**OS**: The OS which the connecting is being established from. For example `os=Android` if your client is running on Android. This is usually hard-coded into the FlipperClient implementation. This string may be used by the Flipper desktop app to identify valid plugins as well as present in the UI to the user.
**DEVICE**: The name of the device running the application. For example `device=iPhone7`.
**DEVICE_ID**: A unique identifier for the device. The Flipper server / desktop app may use this to coalesce multiple connections originating from the save device or present the string in the UI to differentiate between connections to different clients.
**APP**: The name of the app running this client instance. For example `app=Facebook` when connecting to a running facebook app. OS + DEVICE_ID + APP should together uniquely identify a connection.
**FOREGROUND**: A boolean indicating whether this connection was established with a foreground process. This is a hint to the Flipper desktop app of whether to re-focus on this connection or not. For example `foreground=true`. This parameter is recommended but optional.
**SDK_VERSION**: A number indicating the latest protocol version this client is compatible with. You can find the current version in our [C++ connection implementation](https://github.com/facebook/flipper/blob/master/xplat/Flipper/FlipperConnectionManagerImpl.cpp#L37). Usually stored as a constant in the client code, this allows protocol changes to be made whilst still preserving connectivity with old clients. When Flipper desktop encounters an old SDK version, it may attempt to communicate using a matching protocol. However, backwards compatibility is not guaranteed and you should strive to update clients on the rare occasion that the protocol version advances.
## Responding to messages
Flipper uses a simple Remote Procedure Call protocol using JSON-formatted payloads.
The `method` field of the payload indicates which method of the FlipperClient is being called. This will always be present.
The `payload` field contains the JSON parameters for the method call. This may be omitted when no parameters are used.
It is recommended that implementations gracefully ignore extra fields for the sake of backwards and forwards compatibility.
Responses contain either a success object representing the return value of the RPC invocation or an error object indicating that an error occurred.
**The following methods must be implemented by all FlipperClient implementations**:
The syntax used for these type definitions is [Flow](https://flow.org/en/docs/types/objects/). All requests/responses are JSON objects. Where no Response type is specified, it's a void call - no response is expected.
### getPlugins
Return the available plugins as a list of identifiers. A plugin identifier is a string which is matched with the plugin identifier of desktop javascript plugins. This allows the client to specify the plugins it supports.
```
Request = {
"method": "getPlugins",
}
Response = {
"success": {
"plugins": Array<string>
},
}
```
### init
Initialize a plugin. This should result in an onConnected call on the appropriate plugin. Plugins should by nature be lazy and should not be initialized up front as this may incur significant cost. The Flipper desktop client knows when a plugin is needed and should control when to initialize them.
```
Request = {
"method": "init",
"params": {
"plugin": string,
},
}
```
### deinit
Opposite of init. A call to deinit is made when a plugin is no longer needed and should release any resources. Don't rely only on deinit to release plugin resources as Flipper may quit without having the chance to issue a deinit call. In those cases, you should also rely on the RSocket disconnect callbacks. This call is mainly for allowing the desktop app to control the lifecycle of plugins.
```
Request = {
"method": "deinit",
"params": {
"plugin": string,
},
}
```
### execute
This is the main call and how the Flipper desktop plugins and client plugins communicate. When a javascript desktop plugin issues a client request it will be wrapped in one of these execute calls. This execute indicates that the call should be redirected to a plugin.
request.params.api is the plugin id.
request.params.method is the method within the plugin to execute.
request.params.params is an optional params object containing the parameters to the RPC invocation.
```
Request = {
"method": "execute",
"params": {
"api": string,
"method": string,
"params": ?Object,
},
}
Response = {
"success": Object,
} | {
"error": Object,
}
```
## Error Reporting
The Flipper desktop app handles error reporting so you don't have to. If an error occurs during the execution of an RPC invocation, return a serialization of it in the response so it can be attributed to the method call.
If an error occurs in some other context, you can proactively send it to Flipper with the following request structure:
```
Request = {
error: {
message: string,
stacktrace: string,
}
}
```
While in development mode, Flipper will display any client errors next to javascript errors in the Electron/Chrome DevTools console.
## Testing
Testing is incredibly important when building core infrastructure and tools. The following is pseudo code for tests we would expect any new FlipperClient implementation to implement and correctly execute. To run tests we strongly encourage you to build a mock for the RSocket connection to mock out the desktop side of the protocol and to not have any network dependencies in your test code.
```
test("GetPlugins", {
let connection = new MockConnection();
let client = new FlipperClient(connection);
let plugin = {id: "test"};
client.addPlugin(plugin);
client.start();
connection.onReceive({
id: 1,
method: "getPlugins",
});
assert(connection.sentMessages, contains({
id: 1,
success:{
plugins: ["test"],
},
}));
});
```
```
test("InitDeinit", {
let connection = new MockConnection();
let client = new FlipperClient(connection);
let plugin = {id: "test", connected: false};
client.addPlugin(plugin);
client.start();
assertFalse(plugin.connected);
connection.onReceive({
id: 1,
method: "init",
params: {
plugin: "test",
},
});
assertTrue(plugin.connected);
connection.onReceive({
id: 1,
method: "deinit",
params: {
plugin: "test",
},
});
assertFalse(plugin.connected);
});
```
```
test("Disconnect", {
let connection = new MockConnection();
let client = new FlipperClient(connection);
let plugin = {id: "test", connected: false};
client.addPlugin(plugin);
client.start();
assertFalse(plugin.connected);
connection.onReceive({
id: 1,
method: "init",
params: {
plugin: "test",
},
});
assertTrue(plugin.connected);
connection.disconnect();
assertFalse(plugin.connected);
});
```
```
test("Execute", {
let connection = new MockConnection();
let client = new FlipperClient(connection);
let plugin = {
id: "test",
reverse: (params, responder) => {
responder.success({word: params.word.reverse()});
},
};
client.addPlugin(plugin);
client.start();
connection.onReceive({
id: 1,
method: "init",
params: {
plugin: "test",
},
});
connection.onReceive({
id: 1,
method: "execute",
params: {
api: "test",
method: "reverse",
params: {
word: "hello"
},
},
});
assert(connection.sentMessages, contains({
id: 1,
success:{
word: "olleh",
},
}));
});
```