@yume-chan/adb 0.0.15 → 0.0.17

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (196) hide show
  1. package/CHANGELOG.json +33 -0
  2. package/CHANGELOG.md +18 -1
  3. package/LICENSE +21 -21
  4. package/README.md +247 -247
  5. package/esm/adb.d.ts +15 -3
  6. package/esm/adb.d.ts.map +1 -1
  7. package/esm/adb.js +18 -6
  8. package/esm/adb.js.map +1 -1
  9. package/esm/auth.d.ts.map +1 -1
  10. package/esm/auth.js.map +1 -1
  11. package/esm/backend.d.ts +2 -2
  12. package/esm/backend.d.ts.map +1 -1
  13. package/esm/commands/base.d.ts.map +1 -1
  14. package/esm/commands/base.js.map +1 -1
  15. package/esm/commands/framebuffer.d.ts +17 -1
  16. package/esm/commands/framebuffer.d.ts.map +1 -1
  17. package/esm/commands/framebuffer.js +4 -15
  18. package/esm/commands/framebuffer.js.map +1 -1
  19. package/esm/commands/install.d.ts +2 -2
  20. package/esm/commands/install.d.ts.map +1 -1
  21. package/esm/commands/install.js +3 -2
  22. package/esm/commands/install.js.map +1 -1
  23. package/esm/commands/power.d.ts +1 -1
  24. package/esm/commands/power.js +1 -1
  25. package/esm/commands/reverse.d.ts +3 -3
  26. package/esm/commands/reverse.d.ts.map +1 -1
  27. package/esm/commands/reverse.js +9 -9
  28. package/esm/commands/reverse.js.map +1 -1
  29. package/esm/commands/subprocess/command.d.ts +52 -0
  30. package/esm/commands/subprocess/command.d.ts.map +1 -0
  31. package/esm/commands/subprocess/command.js +83 -0
  32. package/esm/commands/subprocess/command.js.map +1 -0
  33. package/esm/commands/subprocess/index.d.ts +1 -53
  34. package/esm/commands/subprocess/index.d.ts.map +1 -1
  35. package/esm/commands/subprocess/index.js +1 -85
  36. package/esm/commands/subprocess/index.js.map +1 -1
  37. package/esm/commands/subprocess/protocols/none.d.ts +5 -4
  38. package/esm/commands/subprocess/protocols/none.d.ts.map +1 -1
  39. package/esm/commands/subprocess/protocols/none.js +11 -8
  40. package/esm/commands/subprocess/protocols/none.js.map +1 -1
  41. package/esm/commands/subprocess/protocols/shell.d.ts +4 -4
  42. package/esm/commands/subprocess/protocols/shell.d.ts.map +1 -1
  43. package/esm/commands/subprocess/protocols/shell.js +6 -6
  44. package/esm/commands/subprocess/protocols/shell.js.map +1 -1
  45. package/esm/commands/subprocess/protocols/types.d.ts +7 -7
  46. package/esm/commands/subprocess/protocols/types.d.ts.map +1 -1
  47. package/esm/commands/sync/index.d.ts +1 -1
  48. package/esm/commands/sync/index.d.ts.map +1 -1
  49. package/esm/commands/sync/index.js +1 -1
  50. package/esm/commands/sync/index.js.map +1 -1
  51. package/esm/commands/sync/list.d.ts +2 -2
  52. package/esm/commands/sync/list.d.ts.map +1 -1
  53. package/esm/commands/sync/list.js +15 -43
  54. package/esm/commands/sync/list.js.map +1 -1
  55. package/esm/commands/sync/pull.d.ts +3 -2
  56. package/esm/commands/sync/pull.d.ts.map +1 -1
  57. package/esm/commands/sync/pull.js +15 -17
  58. package/esm/commands/sync/pull.js.map +1 -1
  59. package/esm/commands/sync/push.d.ts +2 -2
  60. package/esm/commands/sync/push.d.ts.map +1 -1
  61. package/esm/commands/sync/push.js +2 -5
  62. package/esm/commands/sync/push.js.map +1 -1
  63. package/esm/commands/sync/request.d.ts +1 -1
  64. package/esm/commands/sync/request.d.ts.map +1 -1
  65. package/esm/commands/sync/request.js +1 -1
  66. package/esm/commands/sync/request.js.map +1 -1
  67. package/esm/commands/sync/response.d.ts +4 -9
  68. package/esm/commands/sync/response.d.ts.map +1 -1
  69. package/esm/commands/sync/response.js +32 -23
  70. package/esm/commands/sync/response.js.map +1 -1
  71. package/esm/commands/sync/stat.d.ts +3 -3
  72. package/esm/commands/sync/stat.d.ts.map +1 -1
  73. package/esm/commands/sync/stat.js +13 -30
  74. package/esm/commands/sync/stat.js.map +1 -1
  75. package/esm/commands/sync/sync.d.ts +2 -2
  76. package/esm/commands/sync/sync.d.ts.map +1 -1
  77. package/esm/commands/sync/sync.js +7 -5
  78. package/esm/commands/sync/sync.js.map +1 -1
  79. package/esm/crypto.js +1 -1
  80. package/esm/crypto.js.map +1 -1
  81. package/esm/index.d.ts +0 -1
  82. package/esm/index.d.ts.map +1 -1
  83. package/esm/index.js +0 -1
  84. package/esm/index.js.map +1 -1
  85. package/esm/packet.d.ts +1 -1
  86. package/esm/packet.d.ts.map +1 -1
  87. package/esm/packet.js +1 -1
  88. package/esm/packet.js.map +1 -1
  89. package/esm/socket/dispatcher.d.ts +11 -3
  90. package/esm/socket/dispatcher.d.ts.map +1 -1
  91. package/esm/socket/dispatcher.js +19 -11
  92. package/esm/socket/dispatcher.js.map +1 -1
  93. package/esm/socket/index.d.ts +1 -1
  94. package/esm/socket/index.d.ts.map +1 -1
  95. package/esm/socket/index.js +1 -1
  96. package/esm/socket/index.js.map +1 -1
  97. package/esm/socket/socket.d.ts +9 -4
  98. package/esm/socket/socket.d.ts.map +1 -1
  99. package/esm/socket/socket.js +20 -10
  100. package/esm/socket/socket.js.map +1 -1
  101. package/esm/utils/base64.d.ts +23 -0
  102. package/esm/utils/base64.d.ts.map +1 -1
  103. package/esm/utils/base64.js +6 -0
  104. package/esm/utils/base64.js.map +1 -1
  105. package/package.json +13 -14
  106. package/src/adb.ts +285 -273
  107. package/src/auth.ts +174 -173
  108. package/src/backend.ts +12 -11
  109. package/src/commands/base.ts +12 -11
  110. package/src/commands/framebuffer.ts +78 -73
  111. package/src/commands/index.ts +8 -8
  112. package/src/commands/install.ts +32 -30
  113. package/src/commands/power.ts +54 -54
  114. package/src/commands/reverse.ts +141 -140
  115. package/src/commands/subprocess/command.ts +131 -0
  116. package/src/commands/subprocess/index.ts +3 -139
  117. package/src/commands/subprocess/protocols/none.ts +73 -68
  118. package/src/commands/subprocess/protocols/shell.ts +191 -190
  119. package/src/commands/subprocess/protocols/types.ts +60 -59
  120. package/src/commands/subprocess/utils.ts +20 -20
  121. package/src/commands/sync/index.ts +7 -7
  122. package/src/commands/sync/list.ts +54 -86
  123. package/src/commands/sync/pull.ts +45 -46
  124. package/src/commands/sync/push.ts +38 -41
  125. package/src/commands/sync/request.ts +51 -50
  126. package/src/commands/sync/response.ts +68 -64
  127. package/src/commands/sync/stat.ts +129 -150
  128. package/src/commands/sync/sync.ts +182 -181
  129. package/src/commands/tcpip.ts +21 -21
  130. package/src/crypto.ts +296 -296
  131. package/src/features.ts +9 -9
  132. package/src/index.ts +10 -11
  133. package/src/packet.ts +80 -80
  134. package/src/socket/dispatcher.ts +310 -304
  135. package/src/socket/index.ts +2 -2
  136. package/src/socket/socket.ts +156 -144
  137. package/src/utils/auto-reset-event.ts +41 -41
  138. package/src/utils/base64.ts +329 -306
  139. package/src/utils/index.ts +3 -3
  140. package/tsconfig.build.json +3 -3
  141. package/tsconfig.build.tsbuildinfo +1 -1
  142. package/esm/commands/subprocess/legacy.d.ts +0 -35
  143. package/esm/commands/subprocess/legacy.d.ts.map +0 -1
  144. package/esm/commands/subprocess/legacy.js +0 -53
  145. package/esm/commands/subprocess/legacy.js.map +0 -1
  146. package/esm/commands/subprocess/protocol.d.ts +0 -39
  147. package/esm/commands/subprocess/protocol.d.ts.map +0 -1
  148. package/esm/commands/subprocess/protocol.js +0 -157
  149. package/esm/commands/subprocess/protocol.js.map +0 -1
  150. package/esm/commands/subprocess/types.d.ts +0 -50
  151. package/esm/commands/subprocess/types.d.ts.map +0 -1
  152. package/esm/commands/subprocess/types.js +0 -2
  153. package/esm/commands/subprocess/types.js.map +0 -1
  154. package/esm/socket/controller.d.ts +0 -37
  155. package/esm/socket/controller.d.ts.map +0 -1
  156. package/esm/socket/controller.js +0 -66
  157. package/esm/socket/controller.js.map +0 -1
  158. package/esm/stream/buffered.d.ts +0 -35
  159. package/esm/stream/buffered.d.ts.map +0 -1
  160. package/esm/stream/buffered.js +0 -123
  161. package/esm/stream/buffered.js.map +0 -1
  162. package/esm/stream/detect.bak.d.ts +0 -240
  163. package/esm/stream/detect.bak.d.ts.map +0 -1
  164. package/esm/stream/detect.bak.js +0 -60
  165. package/esm/stream/detect.bak.js.map +0 -1
  166. package/esm/stream/detect.d.ts +0 -2
  167. package/esm/stream/detect.d.ts.map +0 -1
  168. package/esm/stream/detect.js +0 -5
  169. package/esm/stream/detect.js.map +0 -1
  170. package/esm/stream/detect.native.d.ts +0 -240
  171. package/esm/stream/detect.native.d.ts.map +0 -1
  172. package/esm/stream/detect.native.js +0 -60
  173. package/esm/stream/detect.native.js.map +0 -1
  174. package/esm/stream/detect.polyfill.d.ts +0 -18
  175. package/esm/stream/detect.polyfill.d.ts.map +0 -1
  176. package/esm/stream/detect.polyfill.js +0 -9
  177. package/esm/stream/detect.polyfill.js.map +0 -1
  178. package/esm/stream/index.d.ts +0 -4
  179. package/esm/stream/index.d.ts.map +0 -1
  180. package/esm/stream/index.js +0 -4
  181. package/esm/stream/index.js.map +0 -1
  182. package/esm/stream/transform.d.ts +0 -104
  183. package/esm/stream/transform.d.ts.map +0 -1
  184. package/esm/stream/transform.js +0 -373
  185. package/esm/stream/transform.js.map +0 -1
  186. package/esm/utils/encoding.d.ts +0 -3
  187. package/esm/utils/encoding.d.ts.map +0 -1
  188. package/esm/utils/encoding.js +0 -11
  189. package/esm/utils/encoding.js.map +0 -1
  190. package/src/stream/buffered.ts +0 -147
  191. package/src/stream/detect.native.ts +0 -362
  192. package/src/stream/detect.polyfill.ts +0 -28
  193. package/src/stream/detect.ts +0 -5
  194. package/src/stream/index.ts +0 -3
  195. package/src/stream/transform.ts +0 -447
  196. package/tsconfig.test.json +0 -10
package/CHANGELOG.json CHANGED
@@ -1,6 +1,39 @@
1
1
  {
2
2
  "name": "@yume-chan/adb",
3
3
  "entries": [
4
+ {
5
+ "version": "0.0.17",
6
+ "tag": "@yume-chan/adb_v0.0.17",
7
+ "date": "Tue, 18 Oct 2022 09:32:30 GMT",
8
+ "comments": {
9
+ "none": [
10
+ {
11
+ "comment": "Move stream utils to separate package"
12
+ }
13
+ ]
14
+ }
15
+ },
16
+ {
17
+ "version": "0.0.16",
18
+ "tag": "@yume-chan/adb_v0.0.16",
19
+ "date": "Sat, 28 May 2022 03:56:37 GMT",
20
+ "comments": {
21
+ "none": [
22
+ {
23
+ "comment": "Upgrade TypeScript to 4.7.2 to enable Node.js ESM"
24
+ },
25
+ {
26
+ "comment": "Upgrade web-streams-polyfill to 4.0.0-beta.3, fix an issue where `Adb#close()` doesn't release the connection."
27
+ },
28
+ {
29
+ "comment": "Fix an issue where `AdbSocket#readable#cancel()` stalls the connection."
30
+ },
31
+ {
32
+ "comment": "Improve performance of `BufferedStream` by up to 100%."
33
+ }
34
+ ]
35
+ }
36
+ },
4
37
  {
5
38
  "version": "0.0.15",
6
39
  "tag": "@yume-chan/adb_v0.0.15",
package/CHANGELOG.md CHANGED
@@ -1,6 +1,23 @@
1
1
  # Change Log - @yume-chan/adb
2
2
 
3
- This log was last generated on Mon, 02 May 2022 04:18:01 GMT and should not be manually modified.
3
+ This log was last generated on Tue, 18 Oct 2022 09:32:30 GMT and should not be manually modified.
4
+
5
+ ## 0.0.17
6
+ Tue, 18 Oct 2022 09:32:30 GMT
7
+
8
+ ### Updates
9
+
10
+ - Move stream utils to separate package
11
+
12
+ ## 0.0.16
13
+ Sat, 28 May 2022 03:56:37 GMT
14
+
15
+ ### Updates
16
+
17
+ - Upgrade TypeScript to 4.7.2 to enable Node.js ESM
18
+ - Upgrade web-streams-polyfill to 4.0.0-beta.3, fix an issue where `Adb#close()` doesn't release the connection.
19
+ - Fix an issue where `AdbSocket#readable#cancel()` stalls the connection.
20
+ - Improve performance of `BufferedStream` by up to 100%.
4
21
 
5
22
  ## 0.0.15
6
23
  Mon, 02 May 2022 04:18:01 GMT
package/LICENSE CHANGED
@@ -1,21 +1,21 @@
1
- MIT License
2
-
3
- Copyright (c) 2020-2022 Simon Chan
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
1
+ MIT License
2
+
3
+ Copyright (c) 2020-2022 Simon Chan
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,247 +1,247 @@
1
- # @yume-chan/adb
2
-
3
- TypeScript implementation of Android Debug Bridge (ADB) protocol.
4
-
5
- **WARNING:** The public API is UNSTABLE. If you have any questions, please open an issue.
6
-
7
- - [Compatibility](#compatibility)
8
- - [Basic usage](#basic-usage)
9
- - [Use without bundlers](#use-without-bundlers)
10
- - [Connection](#connection)
11
- - [Backend](#backend)
12
- - [`connect`](#connect)
13
- - [Authentication](#authentication)
14
- - [AdbCredentialStore](#adbcredentialstore)
15
- - [`generateKey`](#generatekey)
16
- - [`iterateKeys`](#iteratekeys)
17
- - [Implementations](#implementations)
18
- - [AdbAuthenticator](#adbauthenticator)
19
- - [`authenticate`](#authenticate)
20
- - [Stream multiplex](#stream-multiplex)
21
- - [Commands](#commands)
22
- - [subprocess](#subprocess)
23
- - [raw mode](#raw-mode)
24
- - [pty mode](#pty-mode)
25
- - [usb](#usb)
26
- - [tcpip](#tcpip)
27
- - [sync](#sync)
28
- - [LIST](#list)
29
- - [LIS2](#lis2)
30
- - [STAT](#stat)
31
- - [LST2](#lst2)
32
- - [STA2](#sta2)
33
- - [RECV](#recv)
34
- - [RCV2](#rcv2)
35
- - [SEND](#send)
36
- - [SND2](#snd2)
37
- - [Useful links](#useful-links)
38
-
39
- ## Compatibility
40
-
41
- 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.
42
-
43
- Some features can be polyfilled to support older runtimes, but this library doesn't ship with any polyfills.
44
-
45
- Each backend may have different requirements.
46
-
47
- ### Basic usage
48
-
49
- | | Chrome | Edge | Firefox | Internet Explorer | Safari | Node.js |
50
- | ------------------------------- | ------ | ---- | ------- | ----------------- | ------ | ------------------- |
51
- | `@yume-chan/struct`<sup>1</sup> | 67 | 79 | 68 | No | 14 | 8.3<sup>2</sup>, 11 |
52
- | *Overall* | 67 | 79 | No | No | 14.1 | 16.5 |
53
-
54
- <sup>1</sup> `uint64` and `string` are used.
55
-
56
- <sup>2</sup> `TextEncoder` and `TextDecoder` are only available in `util` module. Need to be assigned to `globalThis`.
57
-
58
- ### Use without bundlers
59
-
60
- | | Chrome | Edge | Firefox | Internet Explorer | Safari | Node.js |
61
- | --------------- | ------ | ---- | ------- | ----------------- | ------ | ------- |
62
- | Top-level await | 89 | 89 | 89 | No | 15 | 14.8 |
63
-
64
- ## Connection
65
-
66
- This library doesn't tie to a specific transportation method.
67
-
68
- Instead, a `Backend` is responsible for transferring data in its own way (USB, WebSocket, TCP, etc).
69
-
70
- ### Backend
71
-
72
- #### `connect`
73
-
74
- ```ts
75
- connect(): ValueOrPromise<ReadableWritablePair<AdbPacketCore, AdbPacketInit>>
76
- ```
77
-
78
- Connect to a device and create a pair of `AdbPacket` streams.
79
-
80
- The backend, instead of the core library, 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.
81
-
82
- ## Authentication
83
-
84
- For how does ADB authentication work, see https://chensi.moe/blog/2020/09/30/webadb-part2-connection/#auth.
85
-
86
- In this library, authentication comes in two parts:
87
-
88
- #### AdbCredentialStore
89
-
90
- An interface to generate, store and iterate ADB private keys on each runtime. (Because Node.js and Browsers have different APIs to do this)
91
-
92
- ##### `generateKey`
93
-
94
- ```ts
95
- generateKey(): ValueOrPromise<Uint8Array>
96
- ```
97
-
98
- Generate and store a RSA private key with modulus length `2048` and public exponent `65537`.
99
-
100
- The returned `Uint8Array` is the private key in PKCS #8 format.
101
-
102
- ##### `iterateKeys`
103
-
104
- ```ts
105
- iterateKeys(): Iterator<ArrayBuffer> | AsyncIterator<ArrayBuffer>
106
- ```
107
-
108
- Synchronously or asynchronously iterate through all stored RSA private keys.
109
-
110
- Each call to `iterateKeys` must return a different iterator that iterate through all stored keys.
111
-
112
- ##### Implementations
113
-
114
- 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.
115
-
116
- #### AdbAuthenticator
117
-
118
- An `AdbAuthenticator` generates `AUTH` responses for each `AUTH` request from server.
119
-
120
- This package contains `AdbSignatureAuthenticator` and `AdbPublicKeyAuthenticator`, the two basic modes.
121
-
122
- #### `authenticate`
123
-
124
- ```ts
125
- static async authenticate(
126
- connection: ReadableWritablePair<AdbPacketCore, AdbPacketCore>,
127
- credentialStore: AdbCredentialStore,
128
- authenticators = AdbDefaultAuthenticators,
129
- ): Promise<Adb>
130
- ```
131
-
132
- Call this method to authenticate the connection and create an `Adb` instance.
133
-
134
- If an authentication process failed, it's possible to call `authenticate` again on the same connection (`AdbPacket` stream pair). Every time the device receives a `CNXN` packet, it resets all internal state, and starts a new authentication process.
135
-
136
- ## Stream multiplex
137
-
138
- ADB commands are all based on streams. Multiple streams can send and receive at the same time in one connection.
139
-
140
- 1. Client sends an `OPEN` packet to create a stream.
141
- 2. Server responds with `OKAY` or `FAIL`.
142
- 3. Client and server read/write on the stream.
143
- 4. Client/server sends a `CLSE` to close the stream.
144
-
145
- ## Commands
146
-
147
- ### subprocess
148
-
149
- ADB has two subprocess invocation modes and two data protocols (4 combinations).
150
-
151
- #### raw mode
152
-
153
- In raw mode, Shell protocol transfers `stdout` and `stderr` separately. It also supports returning exit code.
154
-
155
- | | Legacy protocol | Shell Protocol |
156
- | --------------------------- | --------------------------- | ---------------------------- |
157
- | Feature flag | - | `shell_v2` |
158
- | Implementation | `AdbNoneSubprocessProtocol` | `AdbShellSubprocessProtocol` |
159
- | Splitting stdout and stderr | No | Yes |
160
- | Returning exit code | No | Yes |
161
-
162
- Use `spawn` method to create a subprocess in raw mode.
163
-
164
- #### pty mode
165
-
166
- In PTY mode, the subprocess has a pseudo-terminal, so it can send special control sequences like clear screen and set cursor position. The two protocols both send data in `stdout`, but Shell Protocol also supports resizing the terminal from client.
167
-
168
- | | Legacy protocol | Shell Protocol |
169
- | --------------------------- | --------------------------- | ---------------------------- |
170
- | Feature flag | - | `shell_v2` |
171
- | Implementation | `AdbNoneSubprocessProtocol` | `AdbShellSubprocessProtocol` |
172
- | Resizing window | No | Yes |
173
-
174
- Use `shell` method to create a subprocess in PTY mode.
175
-
176
- ### usb
177
-
178
- Disable ADB over WiFi.
179
-
180
- ### tcpip
181
-
182
- Enable ADB over WiFi.
183
-
184
- ### sync
185
-
186
- Client and server will communicate with another protocol on the opened stream.
187
-
188
- #### LIST
189
-
190
- Request server to list the content of a folder.
191
-
192
- #### LIS2
193
-
194
- Version 2 of the LIST command, contains more information.
195
-
196
- Supported on devices with `ls_v2` feature.
197
-
198
- #### STAT
199
-
200
- Request server to return the information of a file.
201
-
202
- If path is a symbolic link, the returned information is about the link itself.
203
-
204
- So it's actually the [`lstat`](https://linux.die.net/man/2/lstat) system call.
205
-
206
- #### LST2
207
-
208
- Version 2 of the STAT command, contains more information.
209
-
210
- Supported on devices with `stat_v2` feature.
211
-
212
- #### STA2
213
-
214
- Basically identical to LST2, but if path is a symbolic link, the information is about the file it refers to.
215
-
216
- Supported on devices with `stat_v2` feature.
217
-
218
- #### RECV
219
-
220
- Request server to send the content of a file.
221
-
222
- #### RCV2
223
-
224
- *(Not Implemented)*
225
-
226
- Version 2 of the RECV command.
227
-
228
- Supported on devices with `sendrecv_v2` feature.
229
-
230
- #### SEND
231
-
232
- *(Not Implemented)*
233
-
234
- Send a file onto server's file system.
235
-
236
- #### SND2
237
-
238
- *(Not Implemented)*
239
-
240
- Version 2 of the SEND command.
241
-
242
- Supported on devices with `sendrecv_v2` feature.
243
-
244
- ## Useful links
245
-
246
- * [ADB protocol overview](https://android.googlesource.com/platform/packages/modules/adb/+/2fd69306184634c6d90db3ed3be5349e71dcc471/OVERVIEW.TXT)
247
- * [ADB commands](https://android.googlesource.com/platform/packages/modules/adb/+/2fd69306184634c6d90db3ed3be5349e71dcc471/SERVICES.TXT#145)
1
+ # @yume-chan/adb
2
+
3
+ TypeScript implementation of Android Debug Bridge (ADB) protocol.
4
+
5
+ **WARNING:** The public API is UNSTABLE. If you have any questions, please open an issue.
6
+
7
+ - [Compatibility](#compatibility)
8
+ - [Basic usage](#basic-usage)
9
+ - [Use without bundlers](#use-without-bundlers)
10
+ - [Connection](#connection)
11
+ - [Backend](#backend)
12
+ - [`connect`](#connect)
13
+ - [Authentication](#authentication)
14
+ - [AdbCredentialStore](#adbcredentialstore)
15
+ - [`generateKey`](#generatekey)
16
+ - [`iterateKeys`](#iteratekeys)
17
+ - [Implementations](#implementations)
18
+ - [AdbAuthenticator](#adbauthenticator)
19
+ - [`authenticate`](#authenticate)
20
+ - [Stream multiplex](#stream-multiplex)
21
+ - [Commands](#commands)
22
+ - [subprocess](#subprocess)
23
+ - [raw mode](#raw-mode)
24
+ - [pty mode](#pty-mode)
25
+ - [usb](#usb)
26
+ - [tcpip](#tcpip)
27
+ - [sync](#sync)
28
+ - [LIST](#list)
29
+ - [LIS2](#lis2)
30
+ - [STAT](#stat)
31
+ - [LST2](#lst2)
32
+ - [STA2](#sta2)
33
+ - [RECV](#recv)
34
+ - [RCV2](#rcv2)
35
+ - [SEND](#send)
36
+ - [SND2](#snd2)
37
+ - [Useful links](#useful-links)
38
+
39
+ ## Compatibility
40
+
41
+ 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.
42
+
43
+ Some features can be polyfilled to support older runtimes, but this library doesn't ship with any polyfills.
44
+
45
+ Each backend may have different requirements.
46
+
47
+ ### Basic usage
48
+
49
+ | | Chrome | Edge | Firefox | Internet Explorer | Safari | Node.js |
50
+ | ------------------------------- | ------ | ---- | ------- | ----------------- | ------ | ------------------- |
51
+ | `@yume-chan/struct`<sup>1</sup> | 67 | 79 | 68 | No | 14 | 8.3<sup>2</sup>, 11 |
52
+ | *Overall* | 67 | 79 | No | No | 14.1 | 16.5 |
53
+
54
+ <sup>1</sup> `uint64` and `string` are used.
55
+
56
+ <sup>2</sup> `TextEncoder` and `TextDecoder` are only available in `util` module. Need to be assigned to `globalThis`.
57
+
58
+ ### Use without bundlers
59
+
60
+ | | Chrome | Edge | Firefox | Internet Explorer | Safari | Node.js |
61
+ | --------------- | ------ | ---- | ------- | ----------------- | ------ | ------- |
62
+ | Top-level await | 89 | 89 | 89 | No | 15 | 14.8 |
63
+
64
+ ## Connection
65
+
66
+ This library doesn't tie to a specific transportation method.
67
+
68
+ Instead, a `Backend` is responsible for transferring data in its own way (USB, WebSocket, TCP, etc).
69
+
70
+ ### Backend
71
+
72
+ #### `connect`
73
+
74
+ ```ts
75
+ connect(): ValueOrPromise<ReadableWritablePair<AdbPacketCore, AdbPacketInit>>
76
+ ```
77
+
78
+ Connect to a device and create a pair of `AdbPacket` streams.
79
+
80
+ The backend, instead of the core library, 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.
81
+
82
+ ## Authentication
83
+
84
+ For how does ADB authentication work, see https://chensi.moe/blog/2020/09/30/webadb-part2-connection/#auth.
85
+
86
+ In this library, authentication comes in two parts:
87
+
88
+ #### AdbCredentialStore
89
+
90
+ An interface to generate, store and iterate ADB private keys on each runtime. (Because Node.js and Browsers have different APIs to do this)
91
+
92
+ ##### `generateKey`
93
+
94
+ ```ts
95
+ generateKey(): ValueOrPromise<Uint8Array>
96
+ ```
97
+
98
+ Generate and store a RSA private key with modulus length `2048` and public exponent `65537`.
99
+
100
+ The returned `Uint8Array` is the private key in PKCS #8 format.
101
+
102
+ ##### `iterateKeys`
103
+
104
+ ```ts
105
+ iterateKeys(): Iterator<ArrayBuffer> | AsyncIterator<ArrayBuffer>
106
+ ```
107
+
108
+ Synchronously or asynchronously iterate through all stored RSA private keys.
109
+
110
+ Each call to `iterateKeys` must return a different iterator that iterate through all stored keys.
111
+
112
+ ##### Implementations
113
+
114
+ 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.
115
+
116
+ #### AdbAuthenticator
117
+
118
+ An `AdbAuthenticator` generates `AUTH` responses for each `AUTH` request from server.
119
+
120
+ This package contains `AdbSignatureAuthenticator` and `AdbPublicKeyAuthenticator`, the two basic modes.
121
+
122
+ #### `authenticate`
123
+
124
+ ```ts
125
+ static async authenticate(
126
+ connection: ReadableWritablePair<AdbPacketCore, AdbPacketCore>,
127
+ credentialStore: AdbCredentialStore,
128
+ authenticators = AdbDefaultAuthenticators,
129
+ ): Promise<Adb>
130
+ ```
131
+
132
+ Call this method to authenticate the connection and create an `Adb` instance.
133
+
134
+ If an authentication process failed, it's possible to call `authenticate` again on the same connection (`AdbPacket` stream pair). Every time the device receives a `CNXN` packet, it resets all internal state, and starts a new authentication process.
135
+
136
+ ## Stream multiplex
137
+
138
+ ADB commands are all based on streams. Multiple streams can send and receive at the same time in one connection.
139
+
140
+ 1. Client sends an `OPEN` packet to create a stream.
141
+ 2. Server responds with `OKAY` or `FAIL`.
142
+ 3. Client and server read/write on the stream.
143
+ 4. Client/server sends a `CLSE` to close the stream.
144
+
145
+ ## Commands
146
+
147
+ ### subprocess
148
+
149
+ ADB has two subprocess invocation modes and two data protocols (4 combinations).
150
+
151
+ #### raw mode
152
+
153
+ In raw mode, Shell protocol transfers `stdout` and `stderr` separately. It also supports returning exit code.
154
+
155
+ | | Legacy protocol | Shell Protocol |
156
+ | --------------------------- | --------------------------- | ---------------------------- |
157
+ | Feature flag | - | `shell_v2` |
158
+ | Implementation | `AdbNoneSubprocessProtocol` | `AdbShellSubprocessProtocol` |
159
+ | Splitting stdout and stderr | No | Yes |
160
+ | Returning exit code | No | Yes |
161
+
162
+ Use `spawn` method to create a subprocess in raw mode.
163
+
164
+ #### pty mode
165
+
166
+ In PTY mode, the subprocess has a pseudo-terminal, so it can send special control sequences like clear screen and set cursor position. The two protocols both send data in `stdout`, but Shell Protocol also supports resizing the terminal from client.
167
+
168
+ | | Legacy protocol | Shell Protocol |
169
+ | --------------------------- | --------------------------- | ---------------------------- |
170
+ | Feature flag | - | `shell_v2` |
171
+ | Implementation | `AdbNoneSubprocessProtocol` | `AdbShellSubprocessProtocol` |
172
+ | Resizing window | No | Yes |
173
+
174
+ Use `shell` method to create a subprocess in PTY mode.
175
+
176
+ ### usb
177
+
178
+ Disable ADB over WiFi.
179
+
180
+ ### tcpip
181
+
182
+ Enable ADB over WiFi.
183
+
184
+ ### sync
185
+
186
+ Client and server will communicate with another protocol on the opened stream.
187
+
188
+ #### LIST
189
+
190
+ Request server to list the content of a folder.
191
+
192
+ #### LIS2
193
+
194
+ Version 2 of the LIST command, contains more information.
195
+
196
+ Supported on devices with `ls_v2` feature.
197
+
198
+ #### STAT
199
+
200
+ Request server to return the information of a file.
201
+
202
+ If path is a symbolic link, the returned information is about the link itself.
203
+
204
+ So it's actually the [`lstat`](https://linux.die.net/man/2/lstat) system call.
205
+
206
+ #### LST2
207
+
208
+ Version 2 of the STAT command, contains more information.
209
+
210
+ Supported on devices with `stat_v2` feature.
211
+
212
+ #### STA2
213
+
214
+ Basically identical to LST2, but if path is a symbolic link, the information is about the file it refers to.
215
+
216
+ Supported on devices with `stat_v2` feature.
217
+
218
+ #### RECV
219
+
220
+ Request server to send the content of a file.
221
+
222
+ #### RCV2
223
+
224
+ *(Not Implemented)*
225
+
226
+ Version 2 of the RECV command.
227
+
228
+ Supported on devices with `sendrecv_v2` feature.
229
+
230
+ #### SEND
231
+
232
+ *(Not Implemented)*
233
+
234
+ Send a file onto server's file system.
235
+
236
+ #### SND2
237
+
238
+ *(Not Implemented)*
239
+
240
+ Version 2 of the SEND command.
241
+
242
+ Supported on devices with `sendrecv_v2` feature.
243
+
244
+ ## Useful links
245
+
246
+ * [ADB protocol overview](https://android.googlesource.com/platform/packages/modules/adb/+/2fd69306184634c6d90db3ed3be5349e71dcc471/OVERVIEW.TXT)
247
+ * [ADB commands](https://android.googlesource.com/platform/packages/modules/adb/+/2fd69306184634c6d90db3ed3be5349e71dcc471/SERVICES.TXT#145)
package/esm/adb.d.ts CHANGED
@@ -1,9 +1,9 @@
1
+ import { WritableStream, type ReadableWritablePair } from '@yume-chan/stream-extra';
1
2
  import { type AdbCredentialStore } from './auth.js';
2
3
  import { AdbPower, AdbReverseCommand, AdbSubprocess, AdbSync, AdbTcpIpCommand, type AdbFrameBuffer } from './commands/index.js';
3
4
  import { AdbFeatures } from './features.js';
4
5
  import { type AdbPacketData, type AdbPacketInit } from './packet.js';
5
6
  import { AdbIncomingSocketHandler, type AdbSocket, type Closeable } from './socket/index.js';
6
- import { WritableStream, type ReadableWritablePair } from "./stream/index.js";
7
7
  export declare enum AdbPropKey {
8
8
  Product = "ro.product.name",
9
9
  Model = "ro.product.model",
@@ -29,14 +29,19 @@ export declare class Adb implements Closeable {
29
29
  private _device;
30
30
  get device(): string | undefined;
31
31
  private _features;
32
- get features(): AdbFeatures[] | undefined;
32
+ get features(): AdbFeatures[];
33
33
  readonly subprocess: AdbSubprocess;
34
34
  readonly power: AdbPower;
35
35
  readonly reverse: AdbReverseCommand;
36
36
  readonly tcpip: AdbTcpIpCommand;
37
37
  constructor(connection: ReadableWritablePair<AdbPacketData, AdbPacketInit>, version: number, maxPayloadSize: number, banner: string);
38
38
  private parseBanner;
39
- addIncomingSocketHandler(handler: AdbIncomingSocketHandler): import("@yume-chan/event").RemoveEventListener;
39
+ /**
40
+ * Add a handler for incoming socket.
41
+ * @param handler A function to call with new incoming sockets. It must return `true` if it accepts the socket.
42
+ * @returns A function to remove the handler.
43
+ */
44
+ onIncomingSocket(handler: AdbIncomingSocketHandler): import("@yume-chan/event").RemoveEventListener;
40
45
  createSocket(service: string): Promise<AdbSocket>;
41
46
  createSocketAndWait(service: string): Promise<string>;
42
47
  getProp(key: string): Promise<string>;
@@ -44,6 +49,13 @@ export declare class Adb implements Closeable {
44
49
  install(): WritableStream<Uint8Array>;
45
50
  sync(): Promise<AdbSync>;
46
51
  framebuffer(): Promise<AdbFrameBuffer>;
52
+ /**
53
+ * Close the ADB connection.
54
+ *
55
+ * Note that it won't close the streams from backends.
56
+ * The streams are both physically and logically intact,
57
+ * and can be reused.
58
+ */
47
59
  close(): Promise<void>;
48
60
  }
49
61
  //# sourceMappingURL=adb.d.ts.map
package/esm/adb.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"adb.d.ts","sourceRoot":"","sources":["../src/adb.ts"],"names":[],"mappings":"AAGA,OAAO,EAA0D,KAAK,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAC5G,OAAO,EAAE,QAAQ,EAAE,iBAAiB,EAAE,aAAa,EAAE,OAAO,EAAE,eAAe,EAAmC,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACjK,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAiC,KAAK,aAAa,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AACpG,OAAO,EAAE,wBAAwB,EAAuB,KAAK,SAAS,EAAE,KAAK,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAClH,OAAO,EAAyD,cAAc,EAAE,KAAK,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAGrI,oBAAY,UAAU;IAClB,OAAO,oBAAoB;IAC3B,KAAK,qBAAqB;IAC1B,MAAM,sBAAsB;IAC5B,QAAQ,aAAa;CACxB;AAED,eAAO,MAAM,qBAAqB,WAAa,CAAC;AAEhD,qBAAa,GAAI,YAAW,SAAS;IACjC;;;;OAIG;WACiB,YAAY,CAC5B,UAAU,EAAE,oBAAoB,CAAC,aAAa,EAAE,aAAa,CAAC,EAC9D,eAAe,EAAE,kBAAkB,EACnC,cAAc,yCAA6B,GAC5C,OAAO,CAAC,GAAG,CAAC;IAqGf,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAsB;IAEjD,IAAW,YAAY,kBAA2C;IAElE,OAAO,CAAC,gBAAgB,CAAqB;IAC7C,IAAW,eAAe,uBAAoC;IAE9D,OAAO,CAAC,QAAQ,CAAqB;IACrC,IAAW,OAAO,uBAA4B;IAE9C,OAAO,CAAC,MAAM,CAAqB;IACnC,IAAW,KAAK,uBAA0B;IAE1C,OAAO,CAAC,OAAO,CAAqB;IACpC,IAAW,MAAM,uBAA2B;IAE5C,OAAO,CAAC,SAAS,CAA4B;IAC7C,IAAW,QAAQ,8BAA6B;IAEhD,SAAgB,UAAU,EAAE,aAAa,CAAC;IAC1C,SAAgB,KAAK,EAAE,QAAQ,CAAC;IAChC,SAAgB,OAAO,EAAE,iBAAiB,CAAC;IAC3C,SAAgB,KAAK,EAAE,eAAe,CAAC;gBAGnC,UAAU,EAAE,oBAAoB,CAAC,aAAa,EAAE,aAAa,CAAC,EAC9D,OAAO,EAAE,MAAM,EACf,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,MAAM;IA+BlB,OAAO,CAAC,WAAW;IAmCZ,wBAAwB,CAAC,OAAO,EAAE,wBAAwB;IAIpD,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;IAIjD,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IASrD,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAOrC,EAAE,CAAC,GAAG,SAAS,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAOjD,OAAO;IAID,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC;IAKxB,WAAW,IAAI,OAAO,CAAC,cAAc,CAAC;IAItC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAGtC"}
1
+ {"version":3,"file":"adb.d.ts","sourceRoot":"","sources":["../src/adb.ts"],"names":[],"mappings":"AAGA,OAAO,EAAyD,cAAc,EAAE,KAAK,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAE3I,OAAO,EAA0D,KAAK,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAC5G,OAAO,EAAE,QAAQ,EAAE,iBAAiB,EAAE,aAAa,EAAE,OAAO,EAAE,eAAe,EAAmC,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACjK,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAiC,KAAK,aAAa,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AACpG,OAAO,EAAE,wBAAwB,EAAuB,KAAK,SAAS,EAAE,KAAK,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAGlH,oBAAY,UAAU;IAClB,OAAO,oBAAoB;IAC3B,KAAK,qBAAqB;IAC1B,MAAM,sBAAsB;IAC5B,QAAQ,aAAa;CACxB;AAED,eAAO,MAAM,qBAAqB,WAAa,CAAC;AAEhD,qBAAa,GAAI,YAAW,SAAS;IACjC;;;;OAIG;WACiB,YAAY,CAC5B,UAAU,EAAE,oBAAoB,CAAC,aAAa,EAAE,aAAa,CAAC,EAC9D,eAAe,EAAE,kBAAkB,EACnC,cAAc,yCAA6B,GAC5C,OAAO,CAAC,GAAG,CAAC;IAsGf,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAsB;IAEjD,IAAW,YAAY,kBAA2C;IAElE,OAAO,CAAC,gBAAgB,CAAqB;IAC7C,IAAW,eAAe,uBAAoC;IAE9D,OAAO,CAAC,QAAQ,CAAqB;IACrC,IAAW,OAAO,uBAA4B;IAE9C,OAAO,CAAC,MAAM,CAAqB;IACnC,IAAW,KAAK,uBAA0B;IAE1C,OAAO,CAAC,OAAO,CAAqB;IACpC,IAAW,MAAM,uBAA2B;IAE5C,OAAO,CAAC,SAAS,CAAqB;IACtC,IAAW,QAAQ,kBAA6B;IAEhD,SAAgB,UAAU,EAAE,aAAa,CAAC;IAC1C,SAAgB,KAAK,EAAE,QAAQ,CAAC;IAChC,SAAgB,OAAO,EAAE,iBAAiB,CAAC;IAC3C,SAAgB,KAAK,EAAE,eAAe,CAAC;gBAGnC,UAAU,EAAE,oBAAoB,CAAC,aAAa,EAAE,aAAa,CAAC,EAC9D,OAAO,EAAE,MAAM,EACf,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,MAAM;IA+BlB,OAAO,CAAC,WAAW;IAiCnB;;;;OAIG;IACI,gBAAgB,CAAC,OAAO,EAAE,wBAAwB;IAI5C,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;IAIjD,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IASrD,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAOrC,EAAE,CAAC,GAAG,SAAS,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAOjD,OAAO;IAID,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC;IAKxB,WAAW,IAAI,OAAO,CAAC,cAAc,CAAC;IAInD;;;;;;OAMG;IACU,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAGtC"}