From 540059368cb186b1c985b36b8b1287b47680c888 Mon Sep 17 00:00:00 2001 From: Cory McWilliams Date: Wed, 6 Mar 2024 20:57:38 -0500 Subject: [PATCH] 11 make docs warnings left, but I'm out of time for tonight. --- src/ssb.db.h | 166 ++++++++++++++++++++++++++++ src/ssb.h | 298 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 464 insertions(+) diff --git a/src/ssb.db.h b/src/ssb.db.h index a8777d48..fa39bda4 100644 --- a/src/ssb.db.h +++ b/src/ssb.db.h @@ -114,47 +114,213 @@ bool tf_ssb_db_blob_store(tf_ssb_t* ssb, const uint8_t* blob, size_t size, char* ** @return The message. */ JSValue tf_ssb_db_get_message_by_id(tf_ssb_t* ssb, const char* id, bool is_keys); + +/** +** Get a message by its author and sequence number. +** @param ssb The SSB instance. +** @param author The author's identity. +** @param sequence The message sequence number. +** @param[out] out_message_id Populated with the message identifier. +** @param out_message_id_size The size of the out_message_id buffer. +** @param[out] out_timestamp Populated with the timestamp. +** @param[out] out_content Populated with the message content. Free with tf_free(). +** @return True if the message was found and retrieved. +*/ bool tf_ssb_db_get_message_by_author_and_sequence( tf_ssb_t* ssb, const char* author, int64_t sequence, char* out_message_id, size_t out_message_id_size, double* out_timestamp, char** out_content); + +/** +** Get information about the last message from an author. +** @param ssb The SSB instance. +** @param author The author's identity. +** @param[out] out_sequence Populated with the message sequence number. +** @param[out] out_message_id Populated with the message identifier. +** @param out_message_id_size The size of the out_message_id buffer. +** @return True if the message was found and information was retrieved. +*/ bool tf_ssb_db_get_latest_message_by_author(tf_ssb_t* ssb, const char* author, int64_t* out_sequence, char* out_message_id, size_t out_message_id_size); + +/** +** Call a function for each result row of an SQL query. +** @param ssb The SSB instance. +** @param query The SQL query. +** @param binds An array of values to bind to SQL parameters. +** @param callback A callback to call for each result row. +** @param user_data User data to pass to the callback. +** @return A promise resolved when the query completes or rejected if it fails. +*/ JSValue tf_ssb_db_visit_query(tf_ssb_t* ssb, const char* query, const JSValue binds, void (*callback)(JSValue row, void* user_data), void* user_data); +/** +** Sanity check the feed for the given author. +** @param db The SQLite database instance to use. +** @param author The identity of the author to check. +** @return True if the author's feed is fully valid. +*/ bool tf_ssb_db_check(sqlite3* db, const char* author); +/** +** Get the number of SSB identities a Tilde Friends user has. +** @param ssb The SSB instance. +** @param user The user's username. +** @return The number of identities found. +*/ int tf_ssb_db_identity_get_count_for_user(tf_ssb_t* ssb, const char* user); + +/** +** Create a new identity for a user. +** @param ssb The SSB instance. +** @param user The user's username. +** @param[out] out_public_key A buffer populated with the new public key. +** @param[out] out_private_key A buffer populated with the new privatee key. +** @return True if the identity was created. +*/ bool tf_ssb_db_identity_create(tf_ssb_t* ssb, const char* user, uint8_t* out_public_key, uint8_t* out_private_key); + +/** +** Delete an identity for a user from the database. This is an unrecoverable operation. +** @param ssb The SSB instance. +** @param user The user's username. +** @param public_key The identity to delete. +** @return True if the identity was deleted. +*/ bool tf_ssb_db_identity_delete(tf_ssb_t* ssb, const char* user, const char* public_key); + +/** +** Add an identity for a user to the database. +** @param ssb The SSB instance. +** @param user The user's username. +** @param public_key The public key of the identity. +** @param private_key The private key of the identity. +*/ bool tf_ssb_db_identity_add(tf_ssb_t* ssb, const char* user, const char* public_key, const char* private_key); + +/** +** Call a function for each identity owned by a user. +** @param ssb The SSB instance. +** @param user The user's username. +** @param callback The function to call for each identity. +** @param user_data User data to pass to the callback. +*/ void tf_ssb_db_identity_visit(tf_ssb_t* ssb, const char* user, void (*callback)(const char* identity, void* user_data), void* user_data); + +/** +** Call a function for all identities in the database. +** @param ssb The SSB instance. +** @param callback The callback to call for each identity. +** @param user_data User data to pass to the callback. +*/ void tf_ssb_db_identity_visit_all(tf_ssb_t* ssb, void (*callback)(const char* identity, void* user_data), void* user_data); + +/** +** Get the private key for an identity in the database. +** @param ssb The SSB instance. +** @param user The owning user's username. +** @param public_key The public key of the identity. +** @param[out] out_private_key A buffer to receive the private key of the identity. +** @param private_key_size The size of the out_private_key buffer. +** @return True if the private key was found and retrieved. +*/ bool tf_ssb_db_identity_get_private_key(tf_ssb_t* ssb, const char* user, const char* public_key, uint8_t* out_private_key, size_t private_key_size); +/** +** Format a message in the standard format for SSB signing. +** @param context A JS context. +** @param previous The previous message identifier. +** @param author The author's public key. +** @param sequence The message sequence number. +** @param timestamp The message timestamp. +** @param hash The hash type (probably "sha256"). +** @param content The message content. +** @param signature The signature of the message. +** @param sequence_before_author The order of the message fields (prefer false). +*/ JSValue tf_ssb_format_message(JSContext* context, const char* previous, const char* author, int64_t sequence, double timestamp, const char* hash, const char* content, const char* signature, bool sequence_before_author); +/** Information about a single followed account. */ typedef struct _tf_ssb_following_t { + /** The number of known users the account is following. */ int following_count; + /** The number of known users the account is blocking. */ int blocking_count; + /** The number of known users following the account. */ int followed_by_count; + /** The number of known users blocking the account. */ int blocked_by_count; + /** The account's identity. */ char id[k_id_base64_len]; } tf_ssb_following_t; +/** +** Get all the identities visible from a set of identities given known follows and blocks. +** @param ssb The SSB instance. +** @param ids An array of identities. +** @param count The number of identities. +** @param depth The following depth to use (prefer 2). +** @return An array of identities. Free with tf_free(). +*/ const char** tf_ssb_db_following_deep_ids(tf_ssb_t* ssb, const char** ids, int count, int depth); + +/** +** Return information about identities visible from a set of identities given known follows and blocks. +** @param ssb The SSB instance. +** @param ids An array of identities. +** @param count The number of identities. +** @param depth The following depth to use (prefer 2). +** @return An array of information about visible accounts. Fere with tf_free(). +*/ tf_ssb_following_t* tf_ssb_db_following_deep(tf_ssb_t* ssb, const char** ids, int count, int depth); + +/** +** Get all visible identities from all local accounts. +** @param ssb The SSB instance. +** @param depth The following depth to consider (prefer 2). +** @return The visible identities. Free with tf_free(). +*/ const char** tf_ssb_db_get_all_visible_identities(tf_ssb_t* ssb, int depth); +/** +** Information about a stored SHS connection. +*/ typedef struct _tf_ssb_db_stored_connection_t { + /** The connection's address. */ char address[256]; + /** The network port number of the connection. */ int port; + /** The identity. */ char pubkey[k_id_base64_len]; } tf_ssb_db_stored_connection_t; +/** +** Get the list of stored connections from the SSB connection tracker. +** @param ssb The SSB instance. +** @param[out] out_count Populated with the number of returned connections. +** @return Information about all the stored connections. +*/ tf_ssb_db_stored_connection_t* tf_ssb_db_get_stored_connections(tf_ssb_t* ssb, int* out_count); + +/** +** Remove a stored connection. +** @param ssb The SSB instance. +** @param address The connection address. +** @param port The connection network port number. +** @param pubkey The identity of the connection. +*/ void tf_ssb_db_forget_stored_connection(tf_ssb_t* ssb, const char* address, int port, const char* pubkey); +/** +** An SQLite authorizer callback. See https://www.sqlite.org/c3ref/set_authorizer.html for use. +** @param user_data User data registered with the authorizer. +** @param action_code The type of action. +** @param arg0 Depends on the action. +** @param arg1 Depends on the action. +** @param arg2 Depends on the action. +** @param arg3 Depends on the action. +** @return A value indicating whether the operation is allowed. +*/ int tf_ssb_sqlite_authorizer(void* user_data, int action_code, const char* arg0, const char* arg1, const char* arg2, const char* arg3); /** @} */ diff --git a/src/ssb.h b/src/ssb.h index a319f67a..71fb6871 100644 --- a/src/ssb.h +++ b/src/ssb.h @@ -514,37 +514,221 @@ void tf_ssb_add_connections_changed_callback(tf_ssb_t* ssb, tf_ssb_connections_c */ void tf_ssb_remove_connections_changed_callback(tf_ssb_t* ssb, tf_ssb_connections_changed_callback_t* callback, void* user_data); +/** +** A callback called when a new broadcast is received or one expires. +** @param ssb The SSB instance. +** @param user_data The user data. +*/ typedef void(tf_ssb_broadcasts_changed_callback_t)(tf_ssb_t* ssb, void* user_data); + +/** +** Register a callback when broadcasts change. +** @param ssb The SSB instance. +** @param callback The callback function. +** @param cleanup A function to call when the callback is removed. +** @param user_data User data to pass to the callback. +*/ void tf_ssb_add_broadcasts_changed_callback(tf_ssb_t* ssb, tf_ssb_broadcasts_changed_callback_t* callback, tf_ssb_callback_cleanup_t* cleanup, void* user_data); + +/** +** Remove a callback registered for when broadcasts changed. +** @param ssb The SSB instance. +** @param callback The callback function. +** @param user_data The user data registered with the callback. +*/ void tf_ssb_remove_broadcasts_changed_callback(tf_ssb_t* ssb, tf_ssb_broadcasts_changed_callback_t* callback, void* user_data); +/** +** A callback called when a message is added to the database. +** @param ssb The SSB instance. +** @param id The message identifier. +** @param user_data The user data. +*/ typedef void(tf_ssb_message_added_callback_t)(tf_ssb_t* ssb, const char* id, void* user_data); + +/** +** Register a callback called when a message is added to the database. +** @param ssb The SSB instance. +** @param callback The callback function. +** @param cleanup A function to call when the callback is removed. +** @param user_data User data to pass to the callback. +*/ void tf_ssb_add_message_added_callback(tf_ssb_t* ssb, tf_ssb_message_added_callback_t* callback, tf_ssb_callback_cleanup_t* cleanup, void* user_data); + +/** +** Remove a callback registered for when a message is added to the database. +** @param ssb The SSB instance. +** @param callback The callback function. +** @param user_data User data registered with the callback. +*/ void tf_ssb_remove_message_added_callback(tf_ssb_t* ssb, tf_ssb_message_added_callback_t* callback, void* user_data); + +/** +** Call all callbacks registered for when a message is added to the database. +** @param ssb The SSB instance. +** @param id The message identity added. +** @param message_with_keys The message added in the format required if keys are requested. +*/ void tf_ssb_notify_message_added(tf_ssb_t* ssb, const char* id, JSValue message_with_keys); + +/** +** Record that a new blob was stored. +** @param ssb The SSB instance. +** @param id The identity of the newly stored blob. +*/ void tf_ssb_notify_blob_stored(tf_ssb_t* ssb, const char* id); +/** +** A callback called when a blob is newly requested. +** @param ssb The SSB instance. +** @param id The blob identity. +** @param user_data The user data. +*/ typedef void(tf_ssb_blob_want_added_callback_t)(tf_ssb_t* ssb, const char* id, void* user_data); + +/** +** Register a function to be called when a blob is newly requested. +** @param ssb The SSB instance. +** @param callback The callback. +** @param cleanup A function to call when the callback is removed. +** @param user_data User data to pass to the callback. +*/ void tf_ssb_add_blob_want_added_callback(tf_ssb_t* ssb, tf_ssb_blob_want_added_callback_t* callback, tf_ssb_callback_cleanup_t* cleanup, void* user_data); + +/** +** Remove a callback registered for when a blob is newly requested. +** @param ssb The SSB instance. +** @param callback The callback to remove. +** @param user_data The user data registered with the callback. +*/ void tf_ssb_remove_blob_want_added_callback(tf_ssb_t* ssb, tf_ssb_blob_want_added_callback_t* callback, void* user_data); + +/** +** Call all callbacks registered for when a blob is newly requested. +** @param ssb The SSB instance. +** @param id The requested blob identity. +*/ void tf_ssb_notify_blob_want_added(tf_ssb_t* ssb, const char* id); +/** +** A function called when a MUXRPC request is made. +** @param connection The SSB connection. +** @param flags The RPC flags. +** @param request_number The request number. +** @param args Request arguments. +** @param message The raw message data. +** @param size The size of the raw message data. +** @param user_data User data registered with the callback. +*/ typedef void(tf_ssb_rpc_callback_t)(tf_ssb_connection_t* connection, uint8_t flags, int32_t request_number, JSValue args, const uint8_t* message, size_t size, void* user_data); + +/** +** Register a MUXRPC callback by name. +** @param ssb The SSB instance. +** @param name The NULL-terminated name. +** @param callback The callback. +** @param cleanup A function to be called when the callback is removed. +** @param user_data User data to pass to the callback. +*/ void tf_ssb_add_rpc_callback(tf_ssb_t* ssb, const char** name, tf_ssb_rpc_callback_t* callback, tf_ssb_callback_cleanup_t* cleanup, void* user_data); + +/** +** Remove a MUXRPC callback. +** @param ssb The SSB instance. +** @param name The NULL-terminated name. +** @param callback The callback to remove. +** @param user_data The user data registered with the callback. +*/ void tf_ssb_remove_rpc_callback(tf_ssb_t* ssb, const char** name, tf_ssb_rpc_callback_t* callback, void* user_data); +/** +** Send a MUXRPC message. +** @param connection The connection on which to send the message. +** @param flags The message flags. +** @param request_number The request number. +** @param message The message payload. +** @param size The size of the message. +** @param callback A callback to call if a response is received. +** @param cleanup A callback to call if the callback is removed. +** @param user_data User data to pass to the callback. +*/ void tf_ssb_connection_rpc_send(tf_ssb_connection_t* connection, uint8_t flags, int32_t request_number, const uint8_t* message, size_t size, tf_ssb_rpc_callback_t* callback, tf_ssb_callback_cleanup_t* cleanup, void* user_data); + +/** +** Send a JSON MUXRPC message. +** @param connection The connection on which to send the message. +** @param flags The message flags. +** @param request_number The request number. +** @param message The JS message payload. +** @param callback A callback to call if a response is received. +** @param cleanup A callback to call if the callback is removed. +** @param user_data User data to pass to the callback. +*/ void tf_ssb_connection_rpc_send_json( tf_ssb_connection_t* connection, uint8_t flags, int32_t request_number, JSValue message, tf_ssb_rpc_callback_t* callback, tf_ssb_callback_cleanup_t* cleanup, void* user_data); + +/** +** Send a MUXRPC error message. +** @param connection The connection on which to send the message. +** @param flags The message flags. +** @param request_number The request number. +** @param error The error string. +*/ void tf_ssb_connection_rpc_send_error(tf_ssb_connection_t* connection, uint8_t flags, int32_t request_number, const char* error); + +/** +** Send a MUXRPC "method not allowed" error message. +** @param connection The connection on which to send the message. +** @param flags The message flags. +** @param request_number The request number. +** @param name The name of the not-allowed method. +*/ void tf_ssb_connection_rpc_send_error_method_not_allowed(tf_ssb_connection_t* connection, uint8_t flags, int32_t request_number, const char* name); + +/** +** Register a callback to be called when a message is received for the given +** request number. +** @param connection The connection on which to register the callback. +** @param request_number The request number. +** @param callback The callback. +** @param cleanup The function to call when the callback is removed. +** @param user_data User data to pass to the callback. +** @param dependent_connection A connection, which, if removed, invalidates this request. +*/ void tf_ssb_connection_add_request(tf_ssb_connection_t* connection, int32_t request_number, tf_ssb_rpc_callback_t* callback, tf_ssb_callback_cleanup_t* cleanup, void* user_data, tf_ssb_connection_t* dependent_connection); + +/** +** Remove a callback registered to be called when a message is received for the +** given request number. +** @param connection The connection. +** @param request_number The request number. +*/ void tf_ssb_connection_remove_request(tf_ssb_connection_t* connection, int32_t request_number); +/** +** A function scheduled to be run later. +** @param connection The owning connection. +** @param user_data User data registered with the callback. +*/ typedef void(tf_ssb_scheduled_callback_t)(tf_ssb_connection_t* connection, void* user_data); + +/** +** Schedule work to be run when the server is next idle. +** @param connection The owning connection. +** @param callback The callback to call. +** @param user_data User data to pass to the callback. +*/ void tf_ssb_connection_schedule_idle(tf_ssb_connection_t* connection, tf_ssb_scheduled_callback_t* callback, void* user_data); + +/** +** Schedule work to run on a worker thread. +** @param connection The owning connection. +** @param work_callback The callback to run on a thread. +** @param after_work_callback The callback to run on the main thread when the work is complete. +** @param user_data User data to pass to the callback. +*/ void tf_ssb_connection_run_work(tf_ssb_connection_t* connection, void (*work_callback)(tf_ssb_connection_t* connection, void* user_data), void (*after_work_callback)(tf_ssb_connection_t* connection, int result, void* user_data), void* user_data); @@ -562,36 +746,150 @@ tf_ssb_connection_t* tf_ssb_connection_tunnel_create(tf_ssb_t* ssb, const char* int32_t tf_ssb_connection_get_ebt_request_number(tf_ssb_connection_t* connection); void tf_ssb_connection_set_ebt_request_number(tf_ssb_connection_t* connection, int32_t request_number); + +/** +** Get the EBT clock for a connection. +** @param connection An SHS connection. +** @return The EBT clock. +*/ JSValue tf_ssb_connection_get_ebt_send_clock(tf_ssb_connection_t* connection); + +/** +** Set the EBT clock for a connection. +** @param connection An SHS connection. +** @param send_clock The clock state. +*/ void tf_ssb_connection_set_ebt_send_clock(tf_ssb_connection_t* connection, JSValue send_clock); + +/** +** Get whether the EBT clock has been sent for a connection. +** @param connection An SHS connection. +** @return True if the clock has been sent. +*/ bool tf_ssb_connection_get_sent_clock(tf_ssb_connection_t* connection); + +/** +** Set the EBT clock sent state for a connection. +** @param connection An SHS connection. +** @param sent_clock Whether the clock has been sent. +*/ void tf_ssb_connection_set_sent_clock(tf_ssb_connection_t* connection, bool sent_clock); +/** +** Get the JS class ID of the SSB connection class. +** @return The class ID +*/ JSClassID tf_ssb_get_connection_class_id(); +/** +** Get general statistics about an SSB instance. +** @param ssb The SSB instance. +** @param[out] out_stats Populated with performance statistics. +*/ void tf_ssb_get_stats(tf_ssb_t* ssb, tf_ssb_stats_t* out_stats); +/** +** Get information about requested blobs. +** @param connection An SHS connection. +** @return Blob wants information. +*/ tf_ssb_blob_wants_t* tf_ssb_connection_get_blob_wants_state(tf_ssb_connection_t* connection); +/** +** Get a report of information about recent disconnections. +** @param ssb The SSB instance. +** @param context A JS context. +** @return Information about disconnections. +*/ JSValue tf_ssb_get_disconnection_debug(tf_ssb_t* ssb, JSContext* context); +/** +** Record whether the calling thread is busy. +** @param ssb The SSB instance. +** @param busy True if the calling thread is now busy. +*/ void tf_ssb_record_thread_busy(tf_ssb_t* ssb, bool busy); + +/** +** Get an estimate of utilization of all running threads. +** @param ssb The SSB instance. +** @return The utilization percent. +*/ float tf_ssb_get_average_thread_percent(tf_ssb_t* ssb); +/** +** Register a callback to be called when the main thread blocks for an +** unreasonable amount of time. +** @param ssb The SSB instance. +** @param callback The callback to call. +** @param user_data User data to pass to the callback. +*/ void tf_ssb_set_hitch_callback(tf_ssb_t* ssb, void (*callback)(const char* name, uint64_t duration_ns, void* user_data), void* user_data); +/** +** Get the queue of messages in the progress of being stored. +** @param ssb The SSB instance. +** @return The queue. +*/ tf_ssb_store_queue_t* tf_ssb_get_store_queue(tf_ssb_t* ssb); +/** +** Increment the SSB instance's ref count. Prevents it from being destroyed +** until it reaches zero. +** @param ssb The SSB instance. +*/ void tf_ssb_ref(tf_ssb_t* ssb); + +/** +** Decrement the SSB instance's ref count. May destroy the instance when the +** count returns to zero. +** @param ssb The SSB instance. +*/ void tf_ssb_unref(tf_ssb_t* ssb); +/** +** Record whether the calling thread is the main thread or not. Some +** operations are disallowed on the main thread for performance. +** @param ssb The SSB instance. +** @param main_thread Whether the calling thread is the main thread. +*/ void tf_ssb_set_main_thread(tf_ssb_t* ssb, bool main_thread); +/** +** Get whether the running server is operating a room. +** @param ssb The SSB instance. +** @return True if the server is a room. +*/ bool tf_ssb_is_room(tf_ssb_t* ssb); + +/** +** Set whether the running server is operating a room. +** @param ssb The SSB instance. +** @param is_room Whether to run a room. +*/ void tf_ssb_set_is_room(tf_ssb_t* ssb, bool is_room); + +/** +** Get the name of the room hosted by the running server. +** @param ssb The SSB instance. +** @return The room name or NULL. +*/ const char* tf_ssb_get_room_name(tf_ssb_t* ssb); + +/** +** Set the name of the room hosted by the running server. +** @param ssb The SSB instance. +** @param room_name The name of the room. +*/ void tf_ssb_set_room_name(tf_ssb_t* ssb, const char* room_name); +/** +** Schedule work to be run after a time delay. +** @param ssb The SSB instance. +** @param delay_ms The duration to wait in milliseconds. +** @param callback The callback to call to run the work. +** @param user_data User data to pass to the callback. +*/ void tf_ssb_schedule_work(tf_ssb_t* ssb, int delay_ms, void (*callback)(tf_ssb_t* ssb, void* user_data), void* user_data); /** @} */