Skip to content

Commit

Permalink
chore(config): add more documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@chicoxyzzy
chicoxyzzy committed Apr 18, 2023
1 parent 6edce55 commit 9a5508a
Show file tree
Hide file tree
Showing 4 changed files with 121 additions and 112 deletions.
214 changes: 107 additions & 107 deletions api/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@


Provides Application level methods

Example usage:
```js
import { createWindow } from 'socket:application'
Expand Down Expand Up @@ -251,7 +251,7 @@ The application's backend instance.
A high-level, cross-platform API for Bluetooth Pub-Sub
Example usage:
```js
import { Bluetooth } from 'socket:bluetooth'
Expand Down Expand Up @@ -325,7 +325,7 @@ Start advertising a new value for a well-known UUID
Some high-level methods around the `crypto.subtle` API for getting
random bytes and hashing.
Example usage:
```js
import { randomBytes } from 'socket:crypto'
Expand Down Expand Up @@ -406,7 +406,7 @@ Generate `size` random bytes.
This module provides an implementation of UDP datagram sockets. It does
not (yet) provide any of the multicast methods or properties.
Example usage:
```js
import { createSocket } from 'socket:dgram'
Expand Down Expand Up @@ -666,7 +666,7 @@ Thrown when a bad port is given.
operating system facilities to perform name resolution. It may not need to
perform any network communication. To perform name resolution the way other
applications on the same system do, use dns.lookup().
Example usage:
```js
import { lookup } from 'socket:dns'
Expand Down Expand Up @@ -715,7 +715,7 @@ Resolves a host name (e.g. `example.org`) into the first found A (IPv4) or
operating system facilities to perform name resolution. It may not need to
perform any network communication. To perform name resolution the way other
applications on the same system do, use dns.lookup().
Example usage:
```js
import { lookup } from 'socket:dns/promises'
Expand Down Expand Up @@ -981,7 +981,7 @@ This is a `FunctionDeclaration` named `writev` in `api/fs/index.js`, it's export
# [FS.promises](https://github.com/socketsupply/socket/blob/master/api/fs/promises.js#L25)
* This module enables interacting with the file system in a way modeled on
standard POSIX functions.
Expand All @@ -997,7 +997,7 @@ This is a `FunctionDeclaration` named `writev` in `api/fs/index.js`, it's export
| `Library/Caches` | The app’s sandboxed caches directory. The contents of this directory are not synchronized via iTunes and may be deleted by the system at any time. It's a good place to store data which provides a good offline-first experience for the user. |
| `Library/Preferences` | The app’s sandboxed preferences directory. The contents of this directory are synchronized via iTunes. Its purpose is to be used by the Settings app. Avoid creating your own files in this directory. |
| `tmp` | The app’s sandboxed temporary directory. The contents of this directory are not synchronized via iTunes and may be deleted by the system at any time. Although, it's recommended that you delete data that is not necessary anymore manually to minimize the space your app takes up on the file system. Use this directory to store data that is only useful during the app runtime. |
Example usage:
```js
import fs from 'socket:fs/promises'
Expand Down Expand Up @@ -1185,7 +1185,7 @@ External docs: https://nodejs.org/dist/latest-v16.x/docs/api/fs.html#fspromisesw
```
ipc://command?key1=value1&key2=value2...
```
Example usage:
```js
import { send } from 'socket:ipc'
Expand Down Expand Up @@ -1226,7 +1226,7 @@ Sends an async IPC command request with parameters.
This module provides normalized system information from all the major
operating systems.
Example usage:
```js
import { arch, platform } from 'socket:os'
Expand Down Expand Up @@ -1297,9 +1297,103 @@ This is a `FunctionDeclaration` named `hrtime` in `api/os.js`, it's exported but
This is a `FunctionDeclaration` named `availableMemory` in `api/os.js`, it's exported but undocumented.
# [Peer](https://github.com/socketsupply/socket/blob/master/api/peer.js#L14)
External docs: https://socketsupply.co/guides/#p2p-guide
Provides a higher level API over the stream-relay protocol.
Example usage:
```js
import { Peer } from 'socket:peer'
```
## [`Peer` (extends `EventEmitter`)](https://github.com/socketsupply/socket/blob/master/api/peer.js#L46)
The Peer class is an EventEmitter. It emits events when new network events
are received (.on), it can also emit new events to the network (.emit).
```js
import { Peer } from 'socket:peer'

const pair = await Peer.createPair()
const clusterId = await Peer.createClusterId()

const peer = new Peer({ ...pair, clusterId })

peer.on('greeting', (value, peer, address, port) => {
console.log(value)
})

const packet = await peer.emit('greeting', { english: 'hello, world' })
```
### [`constructor(options)`](https://github.com/socketsupply/socket/blob/master/api/peer.js#L56)

`Peer` class constructor.

| Argument | Type | Default | Optional | Description |
| :--- | :--- | :---: | :---: | :--- |
| options | Object | | false | All options for the Peer constructor |
| options.publicKey | string | | false | The public key required to sign and read |
| options.privateKey | string | | false | The private key required to sign and read |
| options.clusterId | string | | false | A unique appliction identity |
| options.scheme | string | | false | Specify which encryption scheme to use (ie, 'PTP') |
| options.peers | Array | | false | An array of RemotePeer |


### [`createKeys()`](https://github.com/socketsupply/socket/blob/master/api/peer.js#L80)

A method that will generate a public and private key pair.
The ed25519 pair can be stored by an app with a secure API.


| Return Value | Type | Description |
| :--- | :--- | :--- |
| pair | Object<Pair> | A pair of keys |


### [`createClusterId()`](https://github.com/socketsupply/socket/blob/master/api/peer.js#L94)

Create a clusterId from random bytes

| Return Value | Type | Description |
| :--- | :--- | :--- |
| id | string | a hex encoded sha256 hash |


### [`emit(event, message)`](https://github.com/socketsupply/socket/blob/master/api/peer.js#L105)

Emits a message to the network


| Argument | Type | Default | Optional | Description |
| :--- | :--- | :---: | :---: | :--- |
| event | string | | false | The name of the event to emit to the network |
| message | Buffer | | false | The data to emit to the network |


| Return Value | Type | Description |
| :--- | :--- | :--- |
| Not specified | Object<Packet> | The packet that will be sent when possible |


### [`join()`](https://github.com/socketsupply/socket/blob/master/api/peer.js#L128)

Starts the process of connecting to the network.


| Return Value | Type | Description |
| :--- | :--- | :--- |
| Not specified | Peer | Returns an instance of the underlying network peer |


# [Path](https://github.com/socketsupply/socket/blob/master/api/path/path.js#L9)


Example usage:
```js
import { Path } from 'socket:path'
Expand Down Expand Up @@ -1522,103 +1616,9 @@ Converts this `Path` instance to a string.
| Not specified | string | |


# [Peer](https://github.com/socketsupply/socket/blob/master/api/peer.js#L14)

External docs: https://socketsupply.co/guides/#p2p-guide


Provides a higher level API over the stream-relay protocol.

Example usage:
```js
import { Peer } from 'socket:peer'
```
## [`Peer` (extends `EventEmitter`)](https://github.com/socketsupply/socket/blob/master/api/peer.js#L46)
The Peer class is an EventEmitter. It emits events when new network events
are received (.on), it can also emit new events to the network (.emit).
```js
import { Peer } from 'socket:peer'

const pair = await Peer.createPair()
const clusterId = await Peer.createClusterId()

const peer = new Peer({ ...pair, clusterId })

peer.on('greeting', (value, peer, address, port) => {
console.log(value)
})

const packet = await peer.emit('greeting', { english: 'hello, world' })
```
### [`constructor(options)`](https://github.com/socketsupply/socket/blob/master/api/peer.js#L56)

`Peer` class constructor.

| Argument | Type | Default | Optional | Description |
| :--- | :--- | :---: | :---: | :--- |
| options | Object | | false | All options for the Peer constructor |
| options.publicKey | string | | false | The public key required to sign and read |
| options.privateKey | string | | false | The private key required to sign and read |
| options.clusterId | string | | false | A unique appliction identity |
| options.scheme | string | | false | Specify which encryption scheme to use (ie, 'PTP') |
| options.peers | Array | | false | An array of RemotePeer |


### [`createKeys()`](https://github.com/socketsupply/socket/blob/master/api/peer.js#L80)

A method that will generate a public and private key pair.
The ed25519 pair can be stored by an app with a secure API.


| Return Value | Type | Description |
| :--- | :--- | :--- |
| pair | Object<Pair> | A pair of keys |


### [`createClusterId()`](https://github.com/socketsupply/socket/blob/master/api/peer.js#L94)

Create a clusterId from random bytes

| Return Value | Type | Description |
| :--- | :--- | :--- |
| id | string | a hex encoded sha256 hash |


### [`emit(event, message)`](https://github.com/socketsupply/socket/blob/master/api/peer.js#L105)

Emits a message to the network


| Argument | Type | Default | Optional | Description |
| :--- | :--- | :---: | :---: | :--- |
| event | string | | false | The name of the event to emit to the network |
| message | Buffer | | false | The data to emit to the network |


| Return Value | Type | Description |
| :--- | :--- | :--- |
| Not specified | Object<Packet> | The packet that will be sent when possible |


### [`join()`](https://github.com/socketsupply/socket/blob/master/api/peer.js#L128)

Starts the process of connecting to the network.


| Return Value | Type | Description |
| :--- | :--- | :--- |
| Not specified | Peer | Returns an instance of the underlying network peer |


# [Process](https://github.com/socketsupply/socket/blob/master/api/process.js#L9)


Example usage:
```js
import process from 'socket:process'
Expand Down Expand Up @@ -1672,7 +1672,7 @@ External docs: module:Application Application


Provides ApplicationWindow class and methods

Usaully you don't need to use this module directly, instance of ApplicationWindow
are returned by the methods of the {@link module:Application Application} module.

Expand Down
5 changes: 4 additions & 1 deletion api/config.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,10 @@ version | | A string that indicates the version of the application. It should

Key | Default Value | Description
:--- | :--- | :---
main_activity | | TODO description needed
allow_cleartext | | Allow unencrypted http requests, useful for live reload.
enable_standard_ndk_build | | Enables gradle based ndk build rather than using external native build (standard ndk is the old slow way)
main_activity | | Name of the MainActivity class. Could be overwritten by custom native code.
manifest_permissions | | Which permissions does your application need: https://developer.android.com/guide/topics/permissions/overview

## Section `ios`

Expand Down
1 change: 0 additions & 1 deletion bin/generate-docs.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -299,7 +299,6 @@ const startMarker = 'constexpr auto gDefaultConfig = R"INI('
const endMarker = ')INI";'

const src = path.relative(process.cwd(), 'src/cli/templates.hh')
console.log(src)
const data = fs.readFileSync(src, 'utf8')

const startIndex = data.indexOf(startMarker)
Expand Down
13 changes: 10 additions & 3 deletions src/cli/templates.hh
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1424,11 +1424,18 @@ version = 1.0.0
[android]
; TODO description needed
; Allow unencrypted http requests, useful for live reload.
allow_cleartext = false
; Enables gradle based ndk build rather than using external native build (standard ndk is the old slow way)
enable_standard_ndk_build = false
; Name of the MainActivity class. Could be overwritten by custom native code.
main_activity = ""
; TODO description needed
; home = ""
; Which permissions does your application need: https://developer.android.com/guide/topics/permissions/overview
manifest_permissions = ""
[ios]
Expand Down

0 comments on commit 9a5508a

Please sign in to comment.