OCaml library for JSONfeed parsing and creation
anil.recoil.org
1(*---------------------------------------------------------------------------
2 Copyright (c) 2024 Anil Madhavapeddy. All rights reserved.
3 SPDX-License-Identifier: ISC
4 ---------------------------------------------------------------------------*)
5
6(** Hub endpoints for real-time notifications.
7
8 Hubs describe endpoints that can be used to subscribe to real-time
9 notifications of changes to the feed. This is an optional and rarely-used
10 feature of JSON Feed, primarily for feeds that update frequently.
11
12 @see <https://www.jsonfeed.org/version/1.1/> JSON Feed Specification *)
13
14type t
15(** The type representing a hub endpoint. *)
16
17(** {1 Unknown Fields} *)
18
19module Unknown : sig
20 type t = Jsont.json
21 (** Unknown/unrecognized JSON object members as a generic JSON object.
22 Useful for preserving fields from custom extensions or future spec versions. *)
23
24 val empty : t
25 (** [empty] is the empty list of unknown fields. *)
26
27 val is_empty : t -> bool
28 (** [is_empty u] returns [true] if there are no unknown fields. *)
29end
30
31(** {1 Jsont Type} *)
32
33val jsont : t Jsont.t
34(** Declarative JSON type for hubs.
35
36 Maps JSON objects with "type" and "url" fields (both required). *)
37
38(** {1 Construction} *)
39
40val create : type_:string -> url:string -> ?unknown:Unknown.t -> unit -> t
41(** [create ~type_ ~url ?unknown ()] creates a hub object.
42
43 @param type_ The type of hub protocol (e.g., ["rssCloud"], ["WebSub"])
44 @param url The URL endpoint for the hub
45 @param unknown Unknown/custom fields for extensions (default: empty)
46
47 {b Example:}
48 {[
49 let hub =
50 Hub.create ~type_:"WebSub" ~url:"https://pubsubhubbub.appspot.com/" ()
51 ]} *)
52
53(** {1 Accessors} *)
54
55val type_ : t -> string
56(** [type_ t] returns the hub's protocol type. *)
57
58val url : t -> string
59(** [url t] returns the hub's endpoint URL. *)
60
61val unknown : t -> Unknown.t
62(** [unknown t] returns unrecognized fields from the JSON. *)
63
64(** {1 Comparison} *)
65
66val equal : t -> t -> bool
67(** [equal a b] tests equality between two hubs. *)
68
69(** {1 Pretty Printing} *)
70
71val pp : Format.formatter -> t -> unit
72(** [pp ppf t] pretty prints a hub to the formatter.
73
74 The output is human-readable and suitable for debugging.
75
76 {b Example output:}
77 {v WebSub: https://pubsubhubbub.appspot.com/ v} *)