Skip to content

API.md

Latest commit

 

History

History
845 lines (604 loc) · 28.4 KB

API.md

File metadata and controls

845 lines (604 loc) · 28.4 KB

Classes

App ⇐ Component

Applications can be deployed to the legacy web using App, a powerful template for building modern web applications.

Avatar

Deterministic avatar generator inspired by academic visual hash work (e.g. Perrig/Song "Hash Visualization", a.k.a. "drunken bishop").

The algorithm walks a diagonal "bishop" across a board using bits from SHA-256(input), accumulating visit counts to produce a stable identicon.

Bridge

The Bridge type extends a Fabric application to the web.

HTTPClient

Generic HTTP Client.

Compiler

Builder for Fabric-based applications.

FabricComponent

Generic component.

Definition : Object
FabricDistributedExecutionHTTP
Hub ⇐ Oracle

The Hub is a temporary class in the Fabric HTTP library which handles WebRTC and WebSocket connections, wrapping the core Fabric protocol for legacy web clients (including browsers).

Maki : Object

Maki makes building beautiful apps a breeze.

Remote : Remote

Interact with a remote Resource. This is currently the only HTTP-related code that should remain in @fabric/core — all else must be moved to @fabric/http before final release!

Resource

Generic interface for collections of digital objects.

Router : Object

Simple router.

FabricHTTPServer ⇐ Service

Fabric Service for exposing an Application to clients over HTTP.

Site

Implements a full-capacity (Native + Edge nodes) for a Fabric Site.

SPA ⇐ App

Fully-managed HTML application.

UI

User Interface for a Fabric Actor.

Wallet : Object

Manage keys and track their balances.

Stash

Deprecated 2021-10-16.

Members

jsonRpc

POST JSON-RPC over HTTP; same methods as WebSocket JSONCall when enabled.

static

Passed to express.static (see start()).

cors

When true, send Access-Control-Allow-* for browser clients.

compression

When true, use compression middleware if the package is installed.

sitemap

Sitemap generation settings for /sitemap.xml.

Constants

merge

HTTP surface for distributed execution: manifest and epoch status for operators. Binds routes on a FabricHTTPServer via _addRoute (same pattern as Hub services).

Functions

resolvedPathUnderStaticRoot(relativeCandidate, staticRoot) ⇒ string | null

Resolve relativeCandidate under staticRoot and reject .. / absolute escape attempts.

App ⇐ Component

Applications can be deployed to the legacy web using App, a powerful template for building modern web applications.

Kind: global class
Extends: Component

new App([settings])

Create a Web application.

Returns: App - Instance of the application.

Param Type Default Description
[settings] Object {} Application settings.
[settings.circuit] Circuit Instance of an existing Circuit.
[settings.resources] Object Map of Resource classes.

app._handleNavigation(ctx, next) ⇒ Promise

Trigger navigation.

Kind: instance method of App
Returns: Promise - Resolved on routing complete.

Param Type Description
ctx Context Navigating context.
next function Function called if no route found.

app.render() ⇒ String

Generate the rendered HTML output of the application's user interface.

Kind: instance method of App
Returns: String - HTML string.

app.start() ⇒ Promise

Launches any necessary processes and notifies the user on ready.

Kind: instance method of App
Returns: Promise - Resolves on completion.

Avatar

Deterministic avatar generator inspired by academic visual hash work (e.g. Perrig/Song "Hash Visualization", a.k.a. "drunken bishop").

The algorithm walks a diagonal "bishop" across a board using bits from SHA-256(input), accumulating visit counts to produce a stable identicon.

Kind: global class

new Avatar([input], [settings])

Param Type Default Description
[input] string "''" Seed input used to derive deterministic avatar bytes.
[settings] Object {} Optional rendering configuration (size, colors, grid, steps).

avatar.toASCII() ⇒ String

Render a deterministic ASCII visual hash for terminal/text comparison. Lower visit counts use lighter glyphs; higher counts use denser glyphs.

Kind: instance method of Avatar

avatar.render([settings]) ⇒ String

Render a consumable HTML snippet.

Kind: instance method of Avatar

Param Type Default Description
[settings] Object
[settings.format] 'img' | 'svg' 'img' Output format.
[settings.className] String 'fabric-avatar' CSS class for wrapper output.
[settings.alt] String 'Fabric Avatar' alt label for image output.

Bridge

The Bridge type extends a Fabric application to the web.

Kind: global class

new Bridge([settings])

Create an instance of the bridge by providing a host.

Returns: Bridge - Instance of the bridge.

Param Type Description
[settings] Object Settings for the bridge.

bridge.connect() ⇒ Bridge

Attempt to connect to the target host.

Kind: instance method of Bridge
Returns: Bridge - Instance of the bridge.

bridge.query(request)

Request a Document from our Peers.

Kind: instance method of Bridge

Param Type Description
request Object Request to send.
request.path String Document path.

HTTPClient

Generic HTTP Client.

Kind: global class

new HTTPClient([settings])

Create an instance of an HTTP client.

Param Type Description
[settings] Object Configuration for the client.

Compiler

Builder for Fabric-based applications.

Kind: global class

new Compiler([settings])

Create an instance of the compiler.

Param Type Description
[settings] Object Map of settings.
[settings.document] HTTPComponent Document to use.

compiler.compile([data]) ⇒ String

Build a String representing the HTML-encoded Document.

Kind: instance method of Compiler
Returns: String - Rendered HTML document containing the compiled JavaScript application.

Param Type Description
[data] Mixed Input data to use for local rendering.

compiler._compileToFile(target) ⇒ Boolean

Compiles a Fabric component to an HTML document.

Kind: instance method of Compiler
Returns: Boolean - True if the build succeeded, false if it did not.

Param Type Default Description
target String assets/index.html Path to output HTML.

FabricComponent

Generic component.

Kind: global class

new FabricComponent([settings])

Create a component.

Returns: Component - Fully-configured component.

Param Type Default Description
[settings] Object {} Settings for the component.

fabricComponent._loadHTML([content]) ⇒ String

Load an HTML string into the Component.

Kind: instance method of FabricComponent
Returns: String - HTML document.

Param Type Description
[content] String HTML string to load (empty by default).

fabricComponent.toHTML() ⇒ String

Generate an HTML representation of the component.

Kind: instance method of FabricComponent
Returns: String - HTML of the rendered component.

Definition : Object

Kind: global class
Properties

Name Type Description
name String Human-friendly name for this type.
name String Human-friendly plural name for this type.
routes Object Path hint for retrieving an index.
routes.list String Path hint for retrieving an index.
routes.view String Path hint for retrieving a single entity.

FabricDistributedExecutionHTTP

Kind: global class

new FabricDistributedExecutionHTTP([settings])

Param Type Default Description
[settings] Object
[settings.basePath] string "'/services/distributed'"
[settings.getManifest] function Returns Object or Promise.<Object> JSON manifest.
[settings.getEpochStatus] function Returns Object or Promise.<Object> epoch summary.

fabricDistributedExecutionHTTP.bind(httpServer)

Register routes on an HTTP server instance.

Kind: instance method of FabricDistributedExecutionHTTP

Param Type Description
httpServer Object HTTP server instance exposing _addRoute(method, path, handler).

Hub ⇐ Oracle

The Hub is a temporary class in the Fabric HTTP library which handles WebRTC and WebSocket connections, wrapping the core Fabric protocol for legacy web clients (including browsers).

Kind: global class
Extends: Oracle

new Hub(configuration)

Create an instance of the Hub.

Param Type Description
configuration Object Settings for the Hub.

hub.start()

Start the Hub and listen for incoming connections.

Kind: instance method of Hub

Maki : Object

Maki makes building beautiful apps a breeze.

Kind: global class

new Maki([settings])

Build a new application.

Returns: Maki - Instance of Maki.

Param Type Default Description
[settings] Object {} Configuration for the Maki app.

maki.render() ⇒ String

Generate an HTML string representing the current state of the app.

Kind: instance method of Maki
Returns: String - HTML-encoded string representing the application.

Remote : Remote

Interact with a remote Resource. This is currently the only HTTP-related code that should remain in @fabric/core — all else must be moved to @fabric/http before final release!

Kind: global class
Properties

Name Type
settings Object
secure Boolean

new Remote(target)

An in-memory representation of a node in our network.

Param Type Description
target Object Target object.
target.host String Named host, e.g. "localhost".
target.secure String Require TLS session.

remote.request(type, path, [params]) ⇒ FabricHTTPResult

Make an HTTP request to the configured authority.

Kind: instance method of Remote

Param Type Description
type String One of GET, PUT, POST, DELETE, or OPTIONS.
path String The path to request from the authority.
[params] Object Options.

Resource

Generic interface for collections of digital objects.

Kind: global class

new Resource(definition)

Param Type Description
definition Object Initial parameters

Router : Object

Simple router.

Kind: global class

new Router([settings])

Builds a new Router.

Returns: Router - Instance of the Router.

Param Type Default Description
[settings] Object {} Configuration for the router.

router._addFlat(path, definition) ⇒ Promise

Add a named definition.

Kind: instance method of Router
Returns: Promise - Resolves once added.

Param Type Description
path String Flat path.
definition Object Resource definition?

FabricHTTPServer ⇐ Service

Fabric Service for exposing an Application to clients over HTTP.

Kind: global class
Extends: Service

new FabricHTTPServer([settings])

Create an instance of the HTTP server.

Returns: FabricHTTPServer - Fully-configured instance of the HTTP server.

Param Type Default Description
[settings] Object Configuration values.
[settings.name] String "FabricHTTPServer" User-friendly name of this server.
[settings.port] Number 9999 Port to listen for HTTP connections on.

fabricHTTPServer.webrtcPeerList ⇒ Array

Get a list of WebRTC peers registered with this server (see Hub RegisterWebRTCPeer).

Kind: instance property of FabricHTTPServer
Returns: Array - Array of WebRTC peer objects

fabricHTTPServer.define(name, definition) ⇒ FabricHTTPServer

Define a Type by name.

Kind: instance method of FabricHTTPServer
Returns: FabricHTTPServer - Instance of the configured server.

Param Type Description
name String Human-friendly name of the type.
definition Definition Configuration object for the type.

fabricHTTPServer._isJsonRpcTransportAuthorized(req) ⇒ boolean

Same authorization inputs as HTTP POST JSON-RPC: verified bearer (req.authenticated), raw Bearer on the upgrade/request, or websocket client-token channels.

Kind: instance method of FabricHTTPServer

Param Type Description
req Object Node.js IncomingMessage (HTTP upgrade or Express req).

fabricHTTPServer._handleWebSocket(socket, request) ⇒ WebSocket

Connection manager for WebSockets. Called once the handshake is complete.

Kind: instance method of FabricHTTPServer
Returns: WebSocket - Returns the connected socket.

Param Type Description
socket WebSocket The associated WebSocket.
request http.IncomingMessage Incoming HTTP request.

fabricHTTPServer._handleIndexRequest(req, res)

Special handler for first-page requests.

Kind: instance method of FabricHTTPServer

Param Type Description
req HTTPRequest Incoming request.
res HTTPResponse Outgoing response.

fabricHTTPServer._addRoute(method, path, handler)

Add a route manually.

Kind: instance method of FabricHTTPServer

Param Type Description
method String HTTP verb.
path String HTTP route.
handler function HTTP handler (req, res, next)

fabricHTTPServer._notifySubscribers(path, value)

Notify subscribers of a state change

Kind: instance method of FabricHTTPServer

Param Type Description
path String The path that changed
value * The new value

fabricHTTPServer.formatResponse(req, res, data, options)

Standardized content negotiation for route handlers. Handles JSON/HTML negotiation with proper precedence.

Kind: instance method of FabricHTTPServer

Param Type Description
req Object Express request object
res Object Express response object
data * Data to send
options Object Formatting options
options.title String HTML page title
options.resourceName String Resource name for display
options.resourceType String Resource type (for HTML rendering)

Site

Implements a full-capacity (Native + Edge nodes) for a Fabric Site.

Kind: global class

new Site([settings])

Creates an instance of the Site, which provides general statistics covering a target Fabric node.

Returns: Site - Instance of the Site. Call render(state) to derive a new DOM element.

Param Type Description
[settings] Object Configuration values for the Site.

SPA ⇐ App

Fully-managed HTML application.

Kind: global class
Extends: App

new SPA([settings], [components])

Create a single-page app.

Returns: App - Instance of the application.

Param Type Default Description
[settings] Object {} Settings for the application.
[settings.name] String "@fabric/maki" Name of the app.
[settings.offline] Boolean true Hint offline mode to browsers.
[components] Object Map of Web Components for the application to utilize.

spA.render() ⇒ String

Return a string of HTML for the application.

Kind: instance method of SPA
Overrides: render
Returns: String - Fully-rendered HTML document.

spA._handleNavigation(ctx, next) ⇒ Promise

Trigger navigation.

Kind: instance method of SPA
Overrides: _handleNavigation
Returns: Promise - Resolved on routing complete.

Param Type Description
ctx Context Navigating context.
next function Function called if no route found.

spA.start() ⇒ Promise

Launches any necessary processes and notifies the user on ready.

Kind: instance method of SPA
Overrides: start
Returns: Promise - Resolves on completion.

UI

User Interface for a Fabric Actor.

Kind: global class

Wallet : Object

Manage keys and track their balances.

Kind: global class

new Wallet([settings])

Create an instance of a Wallet.

Returns: Wallet - Instance of the wallet.

Param Type Default Description
[settings] Object {} Configure the wallet.

Stash

Deprecated

Deprecated 2021-10-16.

Kind: global class

jsonRpc

POST JSON-RPC over HTTP; same methods as WebSocket JSONCall when enabled.

Kind: global variable

jsonRpc.requireAuth

When true, HTTP JSON-RPC requires a verified bearer token (request.authenticated).

Kind: static property of jsonRpc

static

Passed to express.static (see start()).

Kind: global variable

cors

When true, send Access-Control-Allow-* for browser clients.

Kind: global variable

compression

When true, use compression middleware if the package is installed.

Kind: global variable

sitemap

Sitemap generation settings for /sitemap.xml.

Kind: global variable

merge

HTTP surface for distributed execution: manifest and epoch status for operators. Binds routes on a FabricHTTPServer via _addRoute (same pattern as Hub services).

Kind: global constant

resolvedPathUnderStaticRoot(relativeCandidate, staticRoot) ⇒ string | null

Resolve relativeCandidate under staticRoot and reject .. / absolute escape attempts.

Kind: global function
Returns: string | null - Absolute path, or null if unsafe / invalid.

Param Type
relativeCandidate string
staticRoot string