From 15d0383349a0841dc88ad47e923db7df03a1d6bc Mon Sep 17 00:00:00 2001 From: Cory McWilliams Date: Wed, 13 Sep 2023 23:00:47 +0000 Subject: [PATCH] api docs work in progress. git-svn-id: https://www.unprompted.com/svn/projects/tildefriends/trunk@4460 ed5197a5-7fde-0310-b194-c3ffbd925b24 --- apps/api/app.js | 40 ++++++++++++++++++++-- apps/api/docs.js | 88 +++++++++++++++++++++++++++++++++++++++++++----- 2 files changed, 117 insertions(+), 11 deletions(-) diff --git a/apps/api/app.js b/apps/api/app.js index 2be984c3..ed99bb7b 100644 --- a/apps/api/app.js +++ b/apps/api/app.js @@ -27,17 +27,51 @@ function markdown(md) { function document(api) { let doc = markdown(docs.docs[api.split(' = ')[0]]); return ` - +

${api}

${doc}
`; } -app.setDocument(` +app.setDocument(` + + + + ${markdown(docs.docs.global)} ${[...treeify('', globalThis)].map(x => document(x)).join('\n')} + ${markdown(docs.docs.database)} ${['database.get()', 'database.set()', 'database.exchange()', 'database.remove()', 'database.getAll()', 'database.getLike()'].map(x => document(x)).join('\n')} ${markdown(docs.docs.tfrpc)} - ${['tfrpc.register()', 'tfprc.rpc.*()'].map(x => document(x)).join('\n')} + ${['tfrpc.register()', 'tfrpc.rpc.*()'].map(x => document(x)).join('\n')} + `); \ No newline at end of file diff --git a/apps/api/docs.js b/apps/api/docs.js index d6db6efc..9b77f609 100644 --- a/apps/api/docs.js +++ b/apps/api/docs.js @@ -1,6 +1,15 @@ export const docs = {}; -docs.global = `# App Globals +docs.global = `# Tilde Friends API Documentation + +Welcome to the Tilde Friends API documentation. + + * [App Globals](#App_Globals) + * [Database Interface](#Database) + * [Remote Procedure Calls](#tfrpc) + + +## App Globals The following are functions and values exposed to all apps in their \`app.js\` or \`handler.js\`. Most of these are asynchronous, returning a \`Promise\` that will be resolved when the call completes, unless noted otherwise. @@ -8,11 +17,14 @@ noted otherwise. This is all a work in progess. These are liable to change without warning. Feedback is welcome. The exposed functions in this API balance multiple competing needs: - * The surface area of the exposed API ought to be fairlyl minimal. If something can be implemented entirely app-side, that is + * The surface area of the exposed API ought to be fairly minimal. If something can be implemented entirely app-side, that is generally preferred over building it into the core. * Everything is built on this API. Ideally the admin app, the SSB app, and the editor all use standard API exposed to all apps, with appropriate permission guards in place making it so that only trusted apps do potentially destructive operations. There will be some things here that aren't necessarily general use to support what's required. + +If you are looking at the [Tilde Friends source code](https://www.tildefriends.net/~cory/releases/), +the vast majority of these are implemented in \`src/*.js.c\` files, and exposed to apps via \`core/core.js\`. `; docs['core.user.credentials.session.name'] = ` @@ -54,6 +66,14 @@ Store a blob in the SSB database. *String* The stored blob ID. `; +docs['ssb.blobGet()'] = ` +Fetches a blob from the database. +### Parameters + * *String* **blob_id** The blob identifier to fetch (\`&....sha256\`). +### Returns +*ArrayBuffer* The blob data. +`; + docs['print()'] = ` Log debug information both to the server's console and to the visiting user's browser console when possible. ### Parameters @@ -74,7 +94,7 @@ Returns a database instance that is specific to the authenticated user and the g * *String* **package_name** The database package name. * *String* **key** The database key. ### Returns - *Database* A database. +*Database* A database. `; docs['shared_database()'] = ` @@ -82,10 +102,30 @@ Returns a database instance that is shared between all users of the app, determi ### Parameters * *String* **key** The database key. ### Returns - *Database* A database. +*Database* A database. `; -docs['utf8Decode()'] =` +docs['base64Decode()'] = ` +Decode a base64 string to bytes. + +Completes synchronously. +### Parameters + * *String* value The base64-encoded string. +### Returns +*Uint8Array* The decoded bytes. +`; + +docs['base64Encode()'] = ` +Encode bytes to a base64 string. + +Completes synchronously. +### Parameters + * *Uint8Array* The bytes to encode. +### Returns +*String* The base64-encoded string. +`; + +docs['utf8Decode()'] = ` Decode UTF-8 bytes to a string. Completes synchronously. @@ -95,7 +135,7 @@ Completes synchronously. *String* The value as a string. `; -docs['utf8Encode()'] =` +docs['utf8Encode()'] = ` Encodes a string to UTF-8 bytes. Completes synchronously. @@ -105,6 +145,37 @@ Completes synchronously. *Uint8Array* The encoded \`value\`. `; +docs['setTimeout()'] = ` +Call a function after some delay. +### Parameters + * *Function* **callback** The function to call. + * *Number* **timeout** Number of milliseconds to wait before calling the callback function. +`; + +docs['parseHttpRequest()'] = ` +Parses an HTTP request. +### Parameters + * *Uint8Array* **request** The request data. Maybe be partial or contain extra data. The return value will + indicate when and where it is complete. + * *Number* **last_length** The length of the data passed on a previous attempt for the same request, or 0 initially. +### Returns + * *Integer* **-2** if the request is incomplete. + * *Integer* **-1** if the request could not be parsed. + * *Object* An object with **bytes_parsed**, **minor_version**, **path**, and **headers** fields on successful parse. +`; + +docs['parseHttpResponse()'] = ` +Parses an HTTP response. +### Parameters + * *Uint8Array* **response** The response data. Maybe be partial or contain extra data. The return value will + indicate when and where it is complete. + * *Number* **last_length** The length of the data passed on a previous attempt for the same response, or 0 initially. +### Returns + * *Integer* **-2** if the response is incomplete. + * *Integer* **-1** if the response could not be parsed. + * *Object* An object with **bytes_parsed**, **minor_version**, **status**, **message**, and **headers** fields on successful parse. +`; + docs['sha1Digest()'] =` Calculates a SHA1 digest. @@ -206,10 +277,11 @@ Removes an entry from the database if it exists. `; docs.tfrpc = ` -# tfrpc +# tfrpc \`tfrpc.js\` is a small helper script that is available to be used to facilitate communication between parts of an application. -\`tfrpc.js\` can be used to asynchronously make calls between the app in the browser and the app process on the server. +\`tfrpc.js\` can be used to asynchronously make calls between the app code running in a sandboxed iframe in the browser +and the app process on the server. From \`app.js\`: \`\`\`