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
14
15(** The type representing a hub endpoint. *)
16type t
17
18
19(** {1 Unknown Fields} *)
20
21module Unknown : sig
22 type t = (string * Jsont.json) list
23 (** Unknown/unrecognized JSON object members.
24 Useful for preserving fields from custom extensions or future spec versions. *)
25
26 val empty : t
27 (** [empty] is the empty list of unknown fields. *)
28
29 val is_empty : t -> bool
30 (** [is_empty u] returns [true] if there are no unknown fields. *)
31end
32
33
34(** {1 Jsont Type} *)
35
36val jsont : t Jsont.t
37(** Declarative JSON type for hubs.
38
39 Maps JSON objects with "type" and "url" fields (both required). *)
40
41
42(** {1 Construction} *)
43
44val create :
45 type_:string -> url:string ->
46 ?unknown:Unknown.t -> unit -> t
47(** [create ~type_ ~url ?unknown ()] creates a hub object.
48
49 @param type_ The type of hub protocol (e.g., ["rssCloud"], ["WebSub"])
50 @param url The URL endpoint for the hub
51 @param unknown Unknown/custom fields for extensions (default: empty)
52
53 {b Example:}
54 {[
55 let hub = Hub.create
56 ~type_:"WebSub"
57 ~url:"https://pubsubhubbub.appspot.com/" ()
58 ]} *)
59
60
61(** {1 Accessors} *)
62
63val type_ : t -> string
64(** [type_ t] returns the hub's protocol type. *)
65
66val url : t -> string
67(** [url t] returns the hub's endpoint URL. *)
68
69val unknown : t -> Unknown.t
70(** [unknown t] returns unrecognized fields from the JSON. *)
71
72
73(** {1 Comparison} *)
74
75val equal : t -> t -> bool
76(** [equal a b] tests equality between two hubs. *)
77
78
79(** {1 Pretty Printing} *)
80
81val pp : Format.formatter -> t -> unit
82(** [pp ppf t] pretty prints a hub to the formatter.
83
84 The output is human-readable and suitable for debugging.
85
86 {b Example output:}
87 {v WebSub: https://pubsubhubbub.appspot.com/ v} *)