<commit_before># Core serverboards RPC calls

# Core

## dir()

Returns list current available methods

## ping()

Returns "pong". To check conectivity.

# Auth

## auth.auth({type, ...})

Tries to do login. If succesfull returns a struct with

* email
* perms

If not success, returns false.

## auth.user()

Returns current user

## auth.set_password(password)

Changes current user password

## auth.create_token

Creates an access token for current user

## group.list
## group.add(name)
## group.remove(name)

## group.list_perms(group)
## group.add_perm(group, perm)
## group.remove_perm(group, perm)

## group.list_users(group)
## group.add_user(group, email)
## group.remove_user(group, email)

## user.list
## user.add(user_struct)
## user.update(email, operations)

User struct is a dict with: {email, first_name, last_name, is_active}

## user.update(email, operations)

Updates user data, for example {"is_active": false, "first_name": "<NAME>"}.

Note that there is no user remove, there is only deactivation via
is_active: false.


# Plugins

Require `plugin` permission

## plugin.start("pluginname/component")

Returns an UUID to be referenced as the plugin

## plugin.alias(uuid, alias)

Creates an alias for that UUID. Only local to caller.

## plugin.call(uuid or alias, method, params)

Performs the call on that uuid or allias

## plugin.stop(uuid or alias)

Stops the plugin.

# Serverboards

## serverboard.add(shortname, attributes)

## serverboard.update(shortname, attributes)

## serverboard.delete(shortname)

## serverboard.list()

## serverboard.info(shortname)

# Services

## service.add(attributes) -> UUID

## service.delete(uuid)

## service.update(uuid, attributes)

## service.list(filter \\ [])

## service.info(uuid)

## service.attach(serverboard_shortname, service_uuid)

## service.detach(serverboard_shortname, service_uuid)
<commit_msg>Updated RPC commands documentation. Preview of events.<commit_after># Core serverboards RPC calls

This is a list of all serverboards calls that the core provides. Each plugin can
provide extra calls that will be documented on each module.

# Core

## dir()

Returns list current available methods

```js
dir()
```

## ping()

Returns "pong". To check conectivity.

```js
ping()
```

# Auth

## auth.auth({type, ...})

Tries to do login. If succesfull returns a struct with

* email
* perms

If not success, returns false.

```js
auth.auth({
  type: "basic",
  username: "<EMAIL>",
  password: "<PASSWORD>"
})
// returns user data as in auth.user
auth.auth({
  type: "token",
  token: "2b8c3<PASSWORD>-12ba-4948-819e-bda<PASSWORD>c<PASSWORD>"
})
// or false
```


## auth.user()

Returns current user

```js
auth.user()
```

Result:
```json
{
  "is_active": true,
  "first_name": "David",
  "last_name": "Moreno",
  "id": 115,
  "email": "<EMAIL>",
  "perms": [
    "auth.modify_self",
    "auth.create_token",
    "auth.manage_groups",
    "auth.modify_any",
    "auth.create_user",
    "auth.info_any_user",
    "auth.modify_groups",
    "auth.modify_self",
    "auth.create_token",
    "plugin"
  ],
  "groups": [
    "admin",
    "user",
    "other"
  ]
}
```


## auth.set_password(password)

Changes current user password

```js
auth.set_password("<PASSWORD>")
```

## auth.create_token

Creates an access token for current user

```js
auth.create_token()
```

Result:
```json
"<PASSWORD>"
```

## group.list

Returns the list of all groups in the system.

```js
group.list()
```

Result:
```json
[
  "admin",
  "user",
  "developers",
  "external",
  "other"
]
```

## group.add(name)

Adds a new group

```js
group.add("newgroup")
```

Result:
```json
"ok"
```

Requires `group.manage_groups` permission.

## group.remove(name)

Adds a new group

```js
group.remove("newgroup")
```

Result:
```json
"ok"
```

Requires `group.manage_groups` permission.

## group.list_perms(group)

Lsits all permissions on that group.

## group.add_perm(group, perm)

Adds a permissions to that group.

## group.remove_perm(group, perm)

Removes a permission from the group.

## group.list_users(group)

Returns a list of all the users at that group. Only returns the emails.

## group.add_user(group, email)
## group.remove_user(group, email)

## user.list

Returns a list of users with email, first_name, last_name, is_active and groups.

## user.add(user_struct)

Adds a user.

## user.update(email, operations)

User struct is a dict with: {email, first_name, last_name, is_active}

## user.update(email, operations)

Updates user data, for example {"is_active": false, "first_name": "new name"}.

Note that there is no user remove, there is only deactivation via
is_active: false.


# Plugins

Require `plugin` permission

## plugin.start("pluginname/component")

Returns an UUID to be referenced as the plugin

## plugin.alias(uuid, alias)

Creates an alias for that UUID. Only local to caller.

## plugin.call(uuid or alias, method, params)

Performs the call on that uuid or allias

## plugin.stop(uuid or alias)

Stops the plugin.

# Serverboards

## serverboard.add(shortname, attributes)

## serverboard.update(shortname, attributes)

## serverboard.delete(shortname)

## serverboard.list()

## serverboard.info(shortname)

# Services

## service.add(attributes) -> UUID

## service.delete(uuid)

## service.update(uuid, attributes)

## service.list(filter \\ [])

## service.info(uuid)

## service.attach(serverboard_shortname, service_uuid)

## service.detach(serverboard_shortname, service_uuid)

# event

Clients can subscribe to an event type, and will be notified when that event happens.

Events can have guards to prevent being sent to clients without the proper
permissions.

Requires `event.subscribe` permission. Without this permission the
client can not subscribe to any event type topic.

# event.subscribe(event_type)

Subscribes to a event_type. All events that this client is allowed to see on
of that type will be emited.

```js
event.subscribe("user.updated")
```

# event.unsubscribe(event_type)

Stop receiving updates on that event_type topic.

```js
event.unsubscribe("user.updated")
```


# event.emit(event_type, extra, guards)

  * `event_type` -- Type of the event, properly scoped (plugin.type)
  * `extra` -- Extra values required to properly update the status
  * `guards` -- Guard expression to prevent being sent to not allowed clients

The guards can be:

 * A list of user required permissions.
 * A dict with `perms` and `context` keys. Perms is the list of required perms,
  and context is a path describing the context, for example: `/serverboard/test`.

Example:

```js
// Has a global foo.bar permission
event.emit("foo.bar", {"text":"hello world"}, ["foo.add"] )
// Has a foo.bar permission at /service/FOO
event.emit("foo.bar", {"text":"hello world"}, {
  "context" : "/service/FOO",
  "perms" : ["foo.add"]
})
```

Requires `event.emit` permission.

{'fraction_non_alphanumeric': 0.13705805325185508, 'fraction_numerical': 0.002182453077258839, 'mean_word_length': 4.382928739232576, 'pattern_counts': {'":': 13, '<': 12, '<?xml version=': 0, '>': 14, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2804807', 'n_tokens_mistral': 2322, 'n_tokens_neox': 2260, 'n_words': 696}