Husk/protocol/jsonrpc.openapi.yaml at main · NGHINAI/Husk · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
openapi: 3.1.0
info:
  title: Husk JSON-RPC API
  version: 0.0.0
  description: |
    JSON-RPC 2.0 over HTTP/1.1 + HTTP/2 (server: Node `http`). Single
    endpoint at /v1/jsonrpc accepting POSTed JSON-RPC envelopes.

    Six methods in v0:
      - health           — server liveness + active session count
      - create_session   — spawn a lightpanda subprocess + open CDP
      - goto             — navigate the session to a URL
      - snapshot         — return a spec-§5.2 JSON-LD snapshot
      - snapshot_diff    — return diff vs prior snapshot, or null
      - close_session    — tear down the session

    Custom JSON-RPC error codes:
      -32001  Session not found
      -32002  Engine error (lightpanda subprocess failure)
      -32003  Lightpanda binary not found
      -32004  Invalid URL

    Plus JSON-RPC 2.0 standard codes (-32600..-32700).
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: http://localhost:7777
    description: Local orchestrator (default)

paths:
  /v1/jsonrpc:
    post:
      summary: JSON-RPC 2.0 endpoint
      operationId: jsonrpc
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/JsonRpcRequest"
      responses:
        "200":
          description: JSON-RPC response (success or error in envelope)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JsonRpcResponse"
        "405":
          description: Method Not Allowed (only POST accepted on this endpoint)

components:
  schemas:
    JsonRpcRequest:
      type: object
      required: [jsonrpc, method, id]
      properties:
        jsonrpc:
          type: string
          const: "2.0"
        method:
          type: string
          enum:
            - health
            - create_session
            - goto
            - snapshot
            - snapshot_diff
            - close_session
        params:
          type: object
        id:
          oneOf: [{ type: string }, { type: integer }]

    JsonRpcResponse:
      type: object
      required: [jsonrpc, id]
      properties:
        jsonrpc:
          type: string
          const: "2.0"
        result: {}
        error:
          $ref: "#/components/schemas/JsonRpcError"
        id:
          oneOf: [{ type: string }, { type: integer }, { type: "null" }]

    JsonRpcError:
      type: object
      required: [code, message]
      properties:
        code:
          type: integer
          description: |
            JSON-RPC error code. Husk custom codes: -32001 (session not
            found), -32002 (engine error), -32003 (binary not found),
            -32004 (invalid URL). Plus JSON-RPC 2.0 standard codes.
        message:
          type: string
        data: {}

    HealthResult:
      type: object
      required: [ok, version, activeSessions]
      properties:
        ok:
          type: boolean
          const: true
        version:
          type: string
        activeSessions:
          type: integer

    CreateSessionResult:
      type: object
      required: [session_id]
      properties:
        session_id:
          type: string

    GotoParams:
      type: object
      required: [session_id, url]
      properties:
        session_id:
          type: string
        url:
          type: string
          format: uri

    SnapshotParams:
      type: object
      required: [session_id]
      properties:
        session_id:
          type: string

    CloseSessionParams:
      type: object
      required: [session_id]
      properties:
        session_id:
          type: string