Document how to extend a Horizon backend

[danielmewes]

Copying this comment from @sunjay https://github.com/rethinkdb/horizon/issues/466 here:

The docs specify that Horizon can be extended to add custom backend functionality:

Horizon exposes a powerful API that allows writing sophisticated realtime applications. However, we carefully designed Horizon to provide an upgrade path in case your application outgrows the Horizon API. If you need to add backend functionality, instead of using the standalone Horizon server you can require Horizon in Node.js as a library, and mix and match Horizon services along with the rest of the Node.js ecosystem. Since Horizon is built on top of RethinkDB, your app will have full access to the underlying database, and you can write arbitrarily complex code without being limited by Horizon’s base APIs and tools.

However I haven't been able to find any documentation about how to do any of that. Can something about this be added?

My use case is some rules that need to be enforced (and hidden). I can't manage with simple validation functions. I want to add a custom endpoint on the backend (or something of that nature) to run my code. How would this look with horizon? Would this be a custom endpoint or would I be adding a method to the horizon object? The docs would hopefully answer these questions.

[danielmewes]

@Tryneus once things get a bit calmer, could you describe the basics of how to extend the Horizon server to perform tasks like this?

[fasiha]

My use case: I have an internal REST API that I want to secure behind Horizon's auth system. That is, I'd like to write a request handler for /some-internal-api that checks to make sure the user is authorized (using the same permissions system as the rest of Horizon), then forwarding the request to an internal URL and returning its response to the user.

(In my case, the internal REST API is unsecured because its users are assumed to deal with authentication/authorization.)

[sylvainlap]

+1

[ivan-kleshnin]

I've got a couple of questions which are not covered in docs. Of course, it's possible to investigate it manually but time is limited and you guys probably appreciate feedbacks ;)

So Horizon DB:

1. What hz_ prefix actually means? Is it to underline that users belongs to app while hz_groups belong to HZ inner stuff? I can imagine I will output hz_groups content in admin panel so I'd like to hear "official" explanation.

2. Permissions are declared inschema.toml and copied to groups table? Couldn't we just declare them right in the table? Is it just for user convenience or involves other reasons?

[danielmewes]

@ivan-kleshnin Yeah, essentially the hz_ prefix means that this table contains metadata internal to Horizon. You can of course access it from your code if you want to, but its format can change in a future Horizon release. The contents of those tables are not part of the official Horizon API.

The answer for 2) is similar. Partially, the hz schema apply command is there for convenience. Additionally, we only try to maintain compatibility for the schema.toml file format, but we might change the internal format in the hz_groups table between versions. If you don't mind that, you can write to the table directly as well. (note that hz schema apply does more than just adding permissions. It also registers and creates collections and secondary indexes)

[ivan-kleshnin]

@danielmewes thank you, that makes sense.

[timothyclemansinsea]

@danielmewes I need to implement https://stripe.com/docs/charges and have no clue how to add my own backend code