mirror of
https://github.com/yume-chan/ya-webadb.git
synced 2025-10-06 03:50:18 +02:00
chore: update docs
This commit is contained in:
Simon Chan
parent
8a521c8d93
commit
82f5a90838
6 changed files with 62 additions and 52 deletions
|
|
@ -5,7 +5,7 @@ Backend for `@yume-chan/adb` using WebUSB ([MDN](https://developer.mozilla.org/e
|
|||
- [Note](#note)
|
||||
- [`pickDevice`](#pickdevice)
|
||||
- [`fromDevice`](#fromdevice)
|
||||
- [`read`/`write`](#readwrite)
|
||||
- [`connect`](#connect)
|
||||
|
||||
## Note
|
||||
|
||||
|
|
@ -36,6 +36,10 @@ static async fromDevice(device: USBDevice): Promise<AdbWebBackend>
|
|||
|
||||
Create an `AdbWebBackend` instance from an exist `USBDevice` instance.
|
||||
|
||||
## `read`/`write`
|
||||
## `connect`
|
||||
|
||||
Read/write data from/to the underlying `USBDevice` instance.
|
||||
```ts
|
||||
async connect(): Promise<ReadableWritablePair<AdbPacketCore, AdbPacketInit>>
|
||||
```
|
||||
|
||||
Connect to a device and create a pair of `AdbPacket` streams.
|
||||
|
|
|
|||
|
|
@ -4,6 +4,6 @@ Backend for `@yume-chan/adb` using WebSocket API.
|
|||
|
||||
Requires WebSockify softwares to bridge the connection between TCP (ADB over Wi-Fi) and WebSocket.
|
||||
|
||||
**WARNING:** WebSocket is an unreliable protocol! When send buffer is full, it will throw away any new-coming data, or even close the connection.
|
||||
**WARNING:** WebSocket is an unreliable protocol! When send buffer is full, it will throw away any new-coming data, or even cut the connection.
|
||||
|
||||
Note: This package only demonstrate the possibility. It's not intended to be used in production, thus not published to NPM registry.
|
||||
|
|
|
|||
|
|
@ -1,18 +1,26 @@
|
|||
# `@yume-chan/adb-credential-web`
|
||||
|
||||
Store ADB credentials in LocalStorage.
|
||||
Generate RSA keys using Web Crypto API ([MDN](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API)) and store them in LocalStorage ([MDN](https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API)).
|
||||
|
||||
- [`generateKey`](#generatekey)
|
||||
- [`iterateKeys`](#iteratekeys)
|
||||
|
||||
## `generateKey`
|
||||
|
||||
**Web Crypto API** ([MDN](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API))
|
||||
|
||||
**Web Storage API** ([MDN](https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API))
|
||||
```ts
|
||||
async generateKey(): Promise<Uint8Array>
|
||||
```
|
||||
|
||||
Generate a RSA private key and store it into LocalStorage.
|
||||
|
||||
Calling this method multiple times will overwrite the previous key.
|
||||
|
||||
The returned `Uint8Array` is the private key in PKCS #8 format.
|
||||
|
||||
## `iterateKeys`
|
||||
|
||||
Return the stored RSA private key. (This backend only supports a single key)
|
||||
```ts
|
||||
*iterateKeys(): Generator<Uint8Array, void, void>
|
||||
```
|
||||
|
||||
Return the stored RSA private key. (This implementation doesn't support storing multiple keys)
|
||||
|
|
|
|||
|
|
@ -10,14 +10,13 @@ TypeScript implementation of Android Debug Bridge (ADB) protocol.
|
|||
- [Connection](#connection)
|
||||
- [Backend](#backend)
|
||||
- [`connect`](#connect)
|
||||
- [`read`](#read)
|
||||
- [`write`](#write)
|
||||
- [Authentication](#authentication)
|
||||
- [AdbCredentialStore](#adbcredentialstore)
|
||||
- [`generateKey`](#generatekey)
|
||||
- [`iterateKeys`](#iteratekeys)
|
||||
- [Implementations](#implementations)
|
||||
- [AdbAuthenticator](#adbauthenticator)
|
||||
- [`authenticate`](#authenticate)
|
||||
- [Stream multiplex](#stream-multiplex)
|
||||
- [Backend](#backend-1)
|
||||
- [Commands](#commands)
|
||||
|
|
@ -38,7 +37,7 @@ TypeScript implementation of Android Debug Bridge (ADB) protocol.
|
|||
|
||||
## Compatibility
|
||||
|
||||
Here is a list of features, their used APIs, and their compatibilities. If you don't use an optional feature, you can ignore its requirement.
|
||||
Here is a list of features, their used APIs, and their compatibilities. If an optional feature is not actually used, its requirements can be ignored.
|
||||
|
||||
Some features can be polyfilled to support older runtimes, but this library doesn't ship with any polyfills.
|
||||
|
||||
|
|
@ -59,8 +58,8 @@ Each backend may have different requirements.
|
|||
### Use without bundlers
|
||||
|
||||
| | Chrome | Edge | Firefox | Internet Explorer | Safari | Node.js |
|
||||
| --------------------------- | ------ | ---- | ------- | ----------------- | ------ | ------- |
|
||||
| Top-level await<sup>1</sup> | 89 | 89 | 89 | No | 15 | 14.8 |
|
||||
| --------------- | ------ | ---- | ------- | ----------------- | ------ | ------- |
|
||||
| Top-level await | 89 | 89 | 89 | No | 15 | 14.8 |
|
||||
|
||||
[MDN_Streams]: https://developer.mozilla.org/en-US/docs/Web/API/Streams_API
|
||||
|
||||
|
|
@ -68,33 +67,19 @@ Each backend may have different requirements.
|
|||
|
||||
This library doesn't tie to a specific transportation method.
|
||||
|
||||
Instead, a `Backend` is responsible for transferring data in its own way (USB, WebSocket, etc).
|
||||
Instead, a `Backend` is responsible for transferring data in its own way (USB, WebSocket, TCP, etc).
|
||||
|
||||
### Backend
|
||||
|
||||
#### `connect`
|
||||
|
||||
Establishes a connection with the device.
|
||||
|
||||
If a backend doesn't have extra steps to establish the connection, it can omit the `connect` method implementation.
|
||||
|
||||
#### `read`
|
||||
|
||||
```ts
|
||||
read(length: number): ArrayBuffer | Promise<ArrayBuffer>
|
||||
connect(): ValueOrPromise<ReadableWritablePair<AdbPacketCore, AdbPacketInit>>
|
||||
```
|
||||
|
||||
Reads the specified amount of data from the underlying connection.
|
||||
Connect to a device and create a pair of `AdbPacket` streams.
|
||||
|
||||
The returned `ArrayBuffer` may have more or less data than the `length` parameter specified, if there is some residual data in the connection buffer. The client will automatically call `read` again with the same `length`.
|
||||
|
||||
#### `write`
|
||||
|
||||
```ts
|
||||
write(buffer: ArrayBuffer): void | Promise<void>
|
||||
```
|
||||
|
||||
Writes data to the underlying connection.
|
||||
The backend is responsible for serializing and deserializing the packets, because it's extreme slow for WebUSB backend (`@yume-chan/adb-backend-webusb`) to read packets with unknown size.
|
||||
|
||||
## Authentication
|
||||
|
||||
|
|
@ -102,22 +87,19 @@ For how does ADB authentication work, see https://chensi.moe/blog/2020/09/30/web
|
|||
|
||||
In this library, authentication comes in two parts:
|
||||
|
||||
* `AdbCredentialStore`: because JavaScript has no unified method to generate, store and iterate crypto keys, an implementation of `AdbCredentialStore` is required for the two built-in authenticators.
|
||||
* `AdbAuthenticator`: can be used to implement custom authentication modes.
|
||||
|
||||
Custom `AdbCredentialStore`s and `AdbAuthenticator`s can be specified in the `Adb#connect` method.
|
||||
|
||||
#### AdbCredentialStore
|
||||
|
||||
An interface to generate, store and iterate ADB private keys on each runtime. (Because Node.js and Browsers have different APIs to do this)
|
||||
|
||||
##### `generateKey`
|
||||
|
||||
```ts
|
||||
generateKey(): ArrayBuffer | Promise<ArrayBuffer>
|
||||
generateKey(): ValueOrPromise<Uint8Array>
|
||||
```
|
||||
|
||||
Generate and store a RSA private key with modulus length `2048` and public exponent `65537`.
|
||||
|
||||
The returned `ArrayBuffer` is the private key in PKCS #8 format.
|
||||
The returned `Uint8Array` is the private key in PKCS #8 format.
|
||||
|
||||
##### `iterateKeys`
|
||||
|
||||
|
|
@ -131,7 +113,7 @@ Each call to `iterateKeys` must return a different iterator that iterate through
|
|||
|
||||
##### Implementations
|
||||
|
||||
The `@yume-chan/adb-backend-webusb` package contains a `AdbWebCredentialStore` implementation using Web Crypto API to generating keys and Web Storage API to storing keys.
|
||||
The `@yume-chan/adb-credential-web` package contains a `AdbWebCredentialStore` implementation using Web Crypto API for generating keys and Web Storage API for storing keys.
|
||||
|
||||
#### AdbAuthenticator
|
||||
|
||||
|
|
@ -139,6 +121,20 @@ An `AdbAuthenticator` generates `AUTH` responses for each `AUTH` request from se
|
|||
|
||||
This package contains `AdbSignatureAuthenticator` and `AdbPublicKeyAuthenticator`, the two basic modes.
|
||||
|
||||
#### `authenticate`
|
||||
|
||||
```ts
|
||||
static async authenticate(
|
||||
connection: ReadableWritablePair<AdbPacketCore, AdbPacketCore>,
|
||||
credentialStore: AdbCredentialStore,
|
||||
authenticators = AdbDefaultAuthenticators,
|
||||
): Promise<Adb>
|
||||
```
|
||||
|
||||
Call this method to authenticate the connection and create an `Adb` instance.
|
||||
|
||||
It's possible to call `authenticate` multiple times on a single connection, every time the device receives a `CNXN` packet, it resets its internal state, and starts a new authentication process.
|
||||
|
||||
## Stream multiplex
|
||||
|
||||
ADB commands are all based on streams. Multiple streams can send and receive at the same time in one connection.
|
||||
|
|
@ -159,15 +155,17 @@ The `Backend` is responsible for reading and writing data from underlying source
|
|||
Spawns child process on server. ADB has two shell modes:
|
||||
|
||||
| | Legacy mode | Shell Protocol |
|
||||
| --------------------------- | ---------------- | ------------------ |
|
||||
| --------------------------- | --------------------------- | ---------------------------- |
|
||||
| Feature flag | - | `shell_v2` |
|
||||
| Implementation | `AdbLegacyShell` | `AdbShellProtocol` |
|
||||
| Implementation | `AdbNoneSubprocessProtocol` | `AdbShellSubprocessProtocol` |
|
||||
| Splitting stdout and stderr | No | Yes |
|
||||
| Returning exit code | No | Yes |
|
||||
| Resizing window | No | Yes |
|
||||
|
||||
The `Adb#childProcess#shell` and `Adb#childProcess#spawn` methods accepts a list of implementations, and will use the first supported one.
|
||||
|
||||
For simple command invocation, usually the `AdbNoneSubprocessProtocol` is enough.
|
||||
|
||||
### usb
|
||||
|
||||
Disable ADB over WiFi.
|
||||
|
|
|
|||
|
|
@ -19,14 +19,14 @@ export const VERSION_OMIT_CHECKSUM = 0x01000001;
|
|||
export class Adb {
|
||||
/**
|
||||
* It's possible to call `authenticate` multiple times on a single connection,
|
||||
* every time the device receives a `CNXN` packet it will reset its internal state,
|
||||
* and begin authentication again.
|
||||
* every time the device receives a `CNXN` packet, it resets its internal state,
|
||||
* and starts a new authentication process.
|
||||
*/
|
||||
public static async authenticate(
|
||||
connection: ReadableWritablePair<AdbPacketCore, AdbPacketCore>,
|
||||
credentialStore: AdbCredentialStore,
|
||||
authenticators = AdbDefaultAuthenticators,
|
||||
) {
|
||||
): Promise<Adb> {
|
||||
let version = 0x01000001;
|
||||
let maxPayloadSize = 0x100000;
|
||||
|
||||
|
|
|
|||
|
|
@ -83,7 +83,7 @@ const buffer = MyStruct.serialize({
|
|||
|
||||
## Compatibility
|
||||
|
||||
Here is a list of features, their used APIs, and their compatibilities. If you don't use an optional feature, you can ignore its requirement.
|
||||
Here is a list of features, their used APIs, and their compatibilities. If an optional feature is not actually used, its requirements can be ignored.
|
||||
|
||||
Some features can be polyfilled to support older runtimes, but this library doesn't ship with any polyfills.
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue