How can bon deal with extension points?

[lu-zero]

wot-td has a fairly complex builder.

Since the W3C Web of Things ThingDescription can be extended in various ways, the main Thing struct is generic on a set of traits and an heterogeneous list is used to allow to extend the struct as you build it.

Since with WoT 2.0 will require quite a number of changes I'm wondering if bon can deal with the pattern we are using so preparing branches with proposed changes wouldn't be more straightforward.

[Veetaha]

Hi! Thank you for creating the discussion.

I've taken a look at the builder approach you use. It's quite a lot of code and it also implements a rather complex typestate. I don't have experience with WoT, so my response is based on a quick review of the code you provided.

For example, your builder makes the form() method available only once finish_extend() is called. It's technically possible to represent this with bon's syntax by defining several builders (one for every type state), where the finish_fn returns a new type of the builder. However, I doubt it'll look nicer. I believe that with the level of the custom type state you require for ThingBuilder, bon will be more of a burden and a limiting factor than a reduction in boilerplate (that I assume you'd like to get). I believe the way you've implemented it today already looks nice.

If you'd like to get a better idea of bon's builders' design and what its limits are, I recommend you to check the bon's Typestate API guide.

Other than that, I see that your builder provides a configuration of sub-objects via closures that accept builders. E.g.:

Thing::builder("...")
    .property("first-property", |prop_builder| {
        prop_builder
            .finish_extend_data_schema()
            .observable(true)
            .bool()
    })

It's also possible to achieve this with bon using custom methods, but there isn't a shorter attribute syntax to express that. I believe such API may be cumbersome to use in more advanced cases. There is some discussion about it at #127. The gist of it is that this pattern has the following problems:

• You can't invoke async functions inside of the closure. E.g. .property(|builder| async { builder.foo(api_call().await) }), unless you make the method accept an async closure specifically
• You can't propagate Result (i.e. do fallible operations) from the closure. E.g. .property(|builder| Ok(builder.foo(fallible()?)))
• You can't do an early return from the surrounding function from within the closure. E.g. .property(|builder| return; ) returns from the closure instead of the surrounding function.
• This makes composition harder. For example, what if you have an already built Property? You can't set it directly property(property), you need to convert it back to the builder: .property(|builder| builder.foo(property.foo).bar(property.bar)). This may also be worsened by the fact, that the builder does some additional runtime validation for the Property when it's built. So Property -> PropertyBuilder conversion may be infallible, but PropertyBuilder -> Property may be fallible (or maybe even async or unsafe?), so it's not easy to convert between each of them.
• You can't easily clone and reuse builders multiple times.

In general, I think T::builder() API is much more flexible and composable. As a real-world example, the crate for Discord API called serenity previously used closure-based API for their builders, but they gave up on this approach and described some of their reasoning in their 0.12 Github release that you can find here.

---

You might also want to take a look at state-shift, which may be the boilerplate reducer for advanced typestate handling.

However, feel free to use bon for simpler cases, where IsSet/IsUnset member state is enough for your needs. All other bon's APIs stem from its TypeState API, and it is built with only these two simple states for every member.

If you have any more questions, you may ask them here on in bon's discord.

[lu-zero]

Thank you for all the pointers, state-shift looks very interesting.

A Thing Description is a subset of json-ld and it is extensible through @context items.

E.g. you may add additional terms for the CoAP protocol calling .ext(CoapProtocol) and you may want to add support form mqtt so you have the hlist of types in the Other generic and have to deal on how to compose them.

To add insult to injury it also has it has context-specific defaults, so you have to accumulate and fail last if something goes wrong.

You may look at how I'm using this feature to build the description and the server in one pass here.