JSLib Reference Manual / Exports / ChannelSocket
Class: ChannelSocket#
ChannelSocket
Hierarchy#
-
↳
ChannelSocket
Table of contents#
Constructors#
Properties#
Accessors#
Methods#
Constructors#
constructor#
• new ChannelSocket(sbServer, onMessage, key?, channelId?)
ChannelSocket constructor
This extends Channel. Use this instead of ChannelEndpoint if you are going to be sending/receiving messages.
You send by calling channel.send(msg: SBMessage | string), i.e. you can send a quick string.
You can set your message handler upon creation, or later by using channel.onMessage = (m: ChannelMessage) => { … }.
This implementation uses websockeds to connect all participating clients through a single servlet (somewhere), with very fast forwarding.
You don’t need to worry about managing resources, like closing it, or checking if it’s open. It will close based on server behavior, eg it’s up to the server to close the connection based on inactivity. The ChannelSocket will re-open if you try to send against a closed connection. You can check status with channelSocket.status if you like, but it shouldn’t be necessary.
Messages are delivered as type ChannelMessage. Usually they are simple blobs of data that are encrypted: the ChannelSocket will decrypt them for you. It also handles a simple ack/nack mechanism with the server transparently.
Be aware that if ChannelSocket doesn’t know how to handle a certain message, it will generally just forward it to you as-is.
Parameters#
Name |
Type |
|---|---|
|
|
|
( |
|
|
|
|
Overrides#
Properties#
admin#
• admin: boolean = false
Inherited from#
adminData#
• Optional adminData: Dictionary<any>
Inherited from#
channelReady#
• channelReady: Promise<Channel>
Channel Class
This is the main work horse for channels. However, it is ABSTRACT, meaning you need a ‘concrete’ class to use it.
Currently you have two options:
You can create a ChannelEndpoint object. That can do everything against a channel except send/receive messages synchronously.
The other option is ChannelSocket, which does everything ChannelEndpoint does, but ALSO connects with a web socket.
So unless you’re actually connecting with intent on interactive, fast messaging, an endpoint is sufficient. In fact, UNLESS you are going to do send/receive, you should use ChannelEndpoint, not ChannelSocket.
In our current thinking, ‘Channel’ captures pretty much everything, except how you want (instant) messaging to be hooked up. So for example, our next class might be ‘ChannelP2P’, which would be setting up webrtc data channel connections in a mesh.
Note that you don’t need to worry about what API calls involve race conditions and which don’t, jslib will do that for you.
Param
server to join
Param
key to use to join (optional)
Param
the Channel Name to find on that server (optional)
Inherited from#
channelSocketReady#
• channelSocketReady: Promise<ChannelSocket>
locked#
• Optional locked: boolean = false
Inherited from#
motd#
• Optional motd: string = ''
Inherited from#
owner#
• owner: boolean = false
Inherited from#
ready#
• ready: Promise<ChannelSocket>
Overrides#
sb384Ready#
• sb384Ready: Promise<SB384>
Inherited from#
userName#
• userName: string = ''
Inherited from#
verifiedGuest#
• verifiedGuest: boolean = false
Inherited from#
Accessors#
_id#
• get _id(): string
Returns#
string
Inherited from#
Channel._id
api#
• get api(): this
Returns#
this
Inherited from#
Channel.api
channelId#
• get channelId(): undefined | string
Returns#
undefined | string
Inherited from#
Channel.channelId
channelSignKey#
• get channelSignKey(): CryptoKey
Returns#
CryptoKey
Inherited from#
Channel.channelSignKey
enableTrace#
• set enableTrace(b): void
Enables debug output
Parameters#
Name |
Type |
|---|---|
|
|
Returns#
void
exportable_owner_pubKey#
• get exportable_owner_pubKey(): CryptoKey
Returns#
CryptoKey
exportable_privateKey#
• get exportable_privateKey(): JsonWebKey
Returns#
JsonWebKey
Inherited from#
Channel.exportable_privateKey
exportable_pubKey#
• get exportable_pubKey(): JsonWebKey
Returns#
JsonWebKey
Inherited from#
Channel.exportable_pubKey
hash#
• get hash(): string
Returns a unique identifier for external use, that will be unique for any class or object that uses SB384 as it’s root.
This is deterministic, used to identify users, channels, etc.
The hash is base64 encoding of the SHA-384 hash of the public key, taking the ‘x’ and ‘y’ fields. Note that it is slightly restricted, it only allows [A-Za-z0-9], eg does not allow the ‘_’ or ‘-’ characters. This makes the encoding more practical for end-user interactions like copy-paste. This is accomplished by simply re-hashing until the result is valid. This reduces the entropy of the channel ID by a neglible amount.
Note this is not b62 encoding, which we use for 256-bit entities. This
is still ~384 bits (e.g. x and y fields are each 384 bits, but of course
the underlying total entropy isn’t that, see
NOTE: if you ever need to COMPARE hashes, well short version is that you cannot do so in the general case. You can use sbCrypto.compareHashWithKey() to compare a hash with a key, but you cannot compare two hashes. See the comparison function for more details.
Returns#
string
Inherited from#
Channel.hash
keys#
• get keys(): ChannelKeys
Returns#
Inherited from#
Channel.keys
onMessage#
• get onMessage(): (m: ChannelMessage) => void
Returns#
fn
▸ (m): void
Parameters#
Name |
Type |
|---|---|
|
Returns#
void
• set onMessage(f): void
Parameters#
Name |
Type |
|---|---|
|
( |
Returns#
void
ownerChannelId#
• get ownerChannelId(): string
Returns#
string
Inherited from#
Channel.ownerChannelId
privateKey#
• get privateKey(): CryptoKey
Returns#
CryptoKey
Inherited from#
Channel.privateKey
readyFlag#
• get readyFlag(): boolean
Returns#
boolean
Inherited from#
Channel.readyFlag
sbServer#
• get sbServer(): SBServer
Returns#
Inherited from#
Channel.sbServer
status#
• get status(): "CLOSED" | "CONNECTING" | "OPEN" | "CLOSING"
Returns#
"CLOSED" | "CONNECTING" | "OPEN" | "CLOSING"
Methods#
acceptVisitor#
▸ acceptVisitor(pubKey): Promise<unknown>
Parameters#
Name |
Type |
|---|---|
|
|
Returns#
Promise<unknown>
Inherited from#
budd#
▸ budd(): Promise<SBChannelHandle>
“budd” will spin a channel off an existing one. You need to provide one of the following combinations of info:
nothing: create new channel and transfer all storage budget
just storage amount: creates new channel with that amount, returns new channel
just a target channel: moves all storage budget to that channel
just keys: creates new channel with those keys and transfers all storage budget
keys and storage amount: creates new channel with those keys and that storage amount
In the first (special) case you can just call budd(), in the other cases you need to fill out the ‘options’ object.
Another way to remember the above: all combinations are valid except both a target channel and assigning keys.
Note: if you’re specifying the target channel, then the return values will not include the private key (that return value will be empty).
Same channels as mother and target will be a no-op, regardless of other parameters.
Note: if you provide a value for ‘storage’, it cannot be undefined. If you wish it to be Infinity, then you need to omit the property from options.
Future: negative amount of storage leaves that amount behind, the rest is transferred
Returns#
Promise<SBChannelHandle>
Inherited from#
▸ budd(options): Promise<SBChannelHandle>
Parameters#
Name |
Type |
|---|---|
|
|
|
|
|
|
|
|
Returns#
Promise<SBChannelHandle>
Inherited from#
downloadData#
▸ downloadData(): Promise<unknown>
Channel.downloadData
Returns#
Promise<unknown>
Inherited from#
getAdminData#
▸ getAdminData(): Promise<ChannelAdminData>
Channel.getAdminData
Returns#
Promise<ChannelAdminData>
Inherited from#
getCapacity#
▸ getCapacity(): Promise<any>
getCapacity
Returns#
Promise<any>
Inherited from#
getJoinRequests#
▸ getJoinRequests(): Promise<any>
getJoinRequests
Returns#
Promise<any>
Inherited from#
getLastMessageTimes#
▸ getLastMessageTimes(): Promise<unknown>
Channel.getLastMessageTimes
Returns#
Promise<unknown>
Inherited from#
getMother#
▸ getMother(): Promise<any>
getMother
Get the channelID from which this channel was budded. Note that this is only accessible by Owner (as well as hosting server)
Returns#
Promise<any>
Inherited from#
getOldMessages#
▸ getOldMessages(currentMessagesLength?, paginate?): Promise<ChannelMessage[]>
Channel.getOldMessages
Will return most recent messages from the channel.
Parameters#
Name |
Type |
Default value |
Description |
|---|---|---|---|
|
|
|
number to fetch (default 100) |
|
|
|
if true, will paginate from last request (default false) |
Returns#
Promise<ChannelMessage[]>
Inherited from#
getStorageLimit#
▸ getStorageLimit(): Promise<any>
getStorageLimit (current storage budget)
Returns#
Promise<any>
Inherited from#
isLocked#
▸ isLocked(): Promise<boolean>
isLocked
Returns#
Promise<boolean>
Inherited from#
lock#
▸ lock(): Promise<unknown>
Channel.lock()
Locks the channel, so that new visitors need an “ack” to join..
Returns#
Promise<unknown>
Inherited from#
ownerKeyRotation#
▸ ownerKeyRotation(): void
Returns#
void
Inherited from#
postPubKey#
▸ postPubKey(_exportable_pubKey): Promise<{ success: boolean }>
Parameters#
Name |
Type |
|---|---|
|
|
Returns#
Promise<{ success: boolean }>
Inherited from#
send#
▸ send(msg): Promise<string>
ChannelSocket.send()
Returns a promise that resolves to “success” when sent, or an error message if it fails.
Parameters#
Name |
Type |
|---|---|
|
|
Returns#
Promise<string>
Overrides#
setMOTD#
▸ setMOTD(motd): Promise<any>
Set message of the day
Parameters#
Name |
Type |
|---|---|
|
|
Returns#
Promise<any>
Inherited from#
storageRequest#
▸ storageRequest(byteLength): Promise<Dictionary<any>>
Parameters#
Name |
Type |
|---|---|
|
|
Returns#
Promise<Dictionary<any>>
Inherited from#
updateCapacity#
▸ updateCapacity(capacity): Promise<any>
Update (set) the capacity of the channel; Owner only
Parameters#
Name |
Type |
|---|---|
|
|
Returns#
Promise<any>
Inherited from#
uploadChannel#
▸ uploadChannel(channelData): Promise<any>
Parameters#
Name |
Type |
|---|---|
|
Returns#
Promise<any>