Skip to content

Commit 739dbca

Browse files
claudeQiyuanqiii
authored andcommitted
docs(api): describe browser network origin constraints
1 parent 1763c88 commit 739dbca

4 files changed

Lines changed: 275 additions & 0 deletions

File tree

‎docs/openapi.json‎

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40887,6 +40887,35 @@
4088740887
},
4088840888
"BrowserNetworkAccessRequestView": {
4088940889
"additionalProperties": false,
40890+
"else": {
40891+
"if": {
40892+
"properties": {
40893+
"browser_network_access": {
40894+
"const": "internet"
40895+
}
40896+
},
40897+
"required": [
40898+
"browser_network_access"
40899+
]
40900+
},
40901+
"then": {
40902+
"properties": {
40903+
"browser_origins": {
40904+
"maxItems": 0
40905+
}
40906+
}
40907+
}
40908+
},
40909+
"if": {
40910+
"properties": {
40911+
"browser_network_access": {
40912+
"const": "restricted"
40913+
}
40914+
},
40915+
"required": [
40916+
"browser_network_access"
40917+
]
40918+
},
4089040919
"properties": {
4089140920
"browser_network_access": {
4089240921
"enum": [
@@ -40897,9 +40926,12 @@
4089740926
"type": "string"
4089840927
},
4089940928
"browser_origins": {
40929+
"description": "At most eight HTTP(S) targets, canonicalized to sorted, deduplicated scheme/host/port origins. Restricted access requires at least one origin; Internet access requires an empty or omitted list. Off may retain inactive origins. Each target must be valid UTF-8 and fit within 4096 UTF-8 bytes both after trimming and after URL canonicalization; this byte limit is enforced by the server, not JSON Schema maxLength.",
4090040930
"items": {
40931+
"minLength": 1,
4090140932
"type": "string"
4090240933
},
40934+
"maxItems": 8,
4090340935
"type": "array"
4090440936
},
4090540937
"expected_revision": {
@@ -40922,10 +40954,49 @@
4092240954
"expected_revision",
4092340955
"browser_network_access"
4092440956
],
40957+
"then": {
40958+
"properties": {
40959+
"browser_origins": {
40960+
"minItems": 1
40961+
}
40962+
},
40963+
"required": [
40964+
"browser_origins"
40965+
]
40966+
},
4092540967
"type": "object"
4092640968
},
4092740969
"BrowserNetworkAccessSelection": {
4092840970
"additionalProperties": false,
40971+
"else": {
40972+
"if": {
40973+
"properties": {
40974+
"browser_network_access": {
40975+
"const": "internet"
40976+
}
40977+
},
40978+
"required": [
40979+
"browser_network_access"
40980+
]
40981+
},
40982+
"then": {
40983+
"properties": {
40984+
"browser_origins": {
40985+
"maxItems": 0
40986+
}
40987+
}
40988+
}
40989+
},
40990+
"if": {
40991+
"properties": {
40992+
"browser_network_access": {
40993+
"const": "restricted"
40994+
}
40995+
},
40996+
"required": [
40997+
"browser_network_access"
40998+
]
40999+
},
4092941000
"properties": {
4093041001
"browser_network_access": {
4093141002
"enum": [
@@ -40936,9 +41007,12 @@
4093641007
"type": "string"
4093741008
},
4093841009
"browser_origins": {
41010+
"description": "At most eight HTTP(S) targets, canonicalized to sorted, deduplicated scheme/host/port origins. Restricted access requires at least one origin; Internet access requires an empty or omitted list. Off may retain inactive origins. Each target must be valid UTF-8 and fit within 4096 UTF-8 bytes both after trimming and after URL canonicalization; this byte limit is enforced by the server, not JSON Schema maxLength.",
4093941011
"items": {
41012+
"minLength": 1,
4094041013
"type": "string"
4094141014
},
41015+
"maxItems": 8,
4094241016
"type": "array"
4094341017
},
4094441018
"for_next_run": {
@@ -40980,10 +41054,49 @@
4098041054
"replayed",
4098141055
"for_next_run"
4098241056
],
41057+
"then": {
41058+
"properties": {
41059+
"browser_origins": {
41060+
"minItems": 1
41061+
}
41062+
},
41063+
"required": [
41064+
"browser_origins"
41065+
]
41066+
},
4098341067
"type": "object"
4098441068
},
4098541069
"BrowserNetworkPreference": {
4098641070
"additionalProperties": false,
41071+
"else": {
41072+
"if": {
41073+
"properties": {
41074+
"browser_network_access": {
41075+
"const": "internet"
41076+
}
41077+
},
41078+
"required": [
41079+
"browser_network_access"
41080+
]
41081+
},
41082+
"then": {
41083+
"properties": {
41084+
"browser_origins": {
41085+
"maxItems": 0
41086+
}
41087+
}
41088+
}
41089+
},
41090+
"if": {
41091+
"properties": {
41092+
"browser_network_access": {
41093+
"const": "restricted"
41094+
}
41095+
},
41096+
"required": [
41097+
"browser_network_access"
41098+
]
41099+
},
4098741100
"properties": {
4098841101
"browser_network_access": {
4098941102
"enum": [
@@ -40994,9 +41107,12 @@
4099441107
"type": "string"
4099541108
},
4099641109
"browser_origins": {
41110+
"description": "At most eight HTTP(S) targets, canonicalized to sorted, deduplicated scheme/host/port origins. Restricted access requires at least one origin; Internet access requires an empty or omitted list. Off may retain inactive origins. Each target must be valid UTF-8 and fit within 4096 UTF-8 bytes both after trimming and after URL canonicalization; this byte limit is enforced by the server, not JSON Schema maxLength.",
4099741111
"items": {
41112+
"minLength": 1,
4099841113
"type": "string"
4099941114
},
41115+
"maxItems": 8,
4100041116
"type": "array"
4100141117
},
4100241118
"revision": {
@@ -41015,6 +41131,16 @@
4101541131
"revision",
4101641132
"browser_network_access"
4101741133
],
41134+
"then": {
41135+
"properties": {
41136+
"browser_origins": {
41137+
"minItems": 1
41138+
}
41139+
},
41140+
"required": [
41141+
"browser_origins"
41142+
]
41143+
},
4101841144
"type": "object"
4101941145
},
4102041146
"BrowserSafeWebReadiness": {
@@ -79432,6 +79558,35 @@
7943279558
},
7943379559
"WorkspaceBrowserNetworkAccessRequestView": {
7943479560
"additionalProperties": false,
79561+
"else": {
79562+
"if": {
79563+
"properties": {
79564+
"browser_network_access": {
79565+
"const": "internet"
79566+
}
79567+
},
79568+
"required": [
79569+
"browser_network_access"
79570+
]
79571+
},
79572+
"then": {
79573+
"properties": {
79574+
"browser_origins": {
79575+
"maxItems": 0
79576+
}
79577+
}
79578+
}
79579+
},
79580+
"if": {
79581+
"properties": {
79582+
"browser_network_access": {
79583+
"const": "restricted"
79584+
}
79585+
},
79586+
"required": [
79587+
"browser_network_access"
79588+
]
79589+
},
7943579590
"properties": {
7943679591
"browser_network_access": {
7943779592
"enum": [
@@ -79442,9 +79597,12 @@
7944279597
"type": "string"
7944379598
},
7944479599
"browser_origins": {
79600+
"description": "At most eight HTTP(S) targets, canonicalized to sorted, deduplicated scheme/host/port origins. Restricted access requires at least one origin; Internet access requires an empty or omitted list. Off may retain inactive origins. Each target must be valid UTF-8 and fit within 4096 UTF-8 bytes both after trimming and after URL canonicalization; this byte limit is enforced by the server, not JSON Schema maxLength.",
7944579601
"items": {
79602+
"minLength": 1,
7944679603
"type": "string"
7944779604
},
79605+
"maxItems": 8,
7944879606
"type": "array"
7944979607
},
7945079608
"expected_revision": {
@@ -79464,6 +79622,16 @@
7946479622
"expected_revision",
7946579623
"browser_network_access"
7946679624
],
79625+
"then": {
79626+
"properties": {
79627+
"browser_origins": {
79628+
"minItems": 1
79629+
}
79630+
},
79631+
"required": [
79632+
"browser_origins"
79633+
]
79634+
},
7946779635
"type": "object"
7946879636
},
7946979637
"WorkspaceCheckpointTimeline": {
Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
package httpapi
2+
3+
import (
4+
"bytes"
5+
"encoding/json"
6+
"strings"
7+
"testing"
8+
9+
"github.com/santhosh-tekuri/jsonschema/v5"
10+
)
11+
12+
func TestBrowserNetworkAccessOpenAPIOriginConstraints(t *testing.T) {
13+
raw, err := GenerateOpenAPI()
14+
if err != nil {
15+
t.Fatal(err)
16+
}
17+
compiler := jsonschema.NewCompiler()
18+
compiler.Draft = jsonschema.Draft2020
19+
if err := compiler.AddResource("browser-network-openapi.json", bytes.NewReader(raw)); err != nil {
20+
t.Fatal(err)
21+
}
22+
var document openAPIDocument
23+
if err := json.Unmarshal(raw, &document); err != nil {
24+
t.Fatal(err)
25+
}
26+
for _, name := range []string{"BrowserNetworkAccessRequestView", "WorkspaceBrowserNetworkAccessRequestView", "BrowserNetworkAccessSelection", "BrowserNetworkPreference"} {
27+
t.Run(name, func(t *testing.T) {
28+
schema, err := compiler.Compile("browser-network-openapi.json#/components/schemas/" + name)
29+
if err != nil {
30+
t.Fatal(err)
31+
}
32+
origins := document.Components.Schemas[name]["properties"].(map[string]any)["browser_origins"].(map[string]any)
33+
items := origins["items"].(map[string]any)
34+
if _, exists := items["maxLength"]; exists || !strings.Contains(origins["description"].(string), "4096 UTF-8 bytes") {
35+
t.Fatal("URL byte limit must be documented without a character-count maxLength")
36+
}
37+
eight := make([]any, 8)
38+
for index := range eight {
39+
eight[index] = "https://example.org"
40+
}
41+
for _, tc := range []struct {
42+
mode string
43+
origins []any
44+
valid bool
45+
}{
46+
{"off", nil, true}, {"off", []any{}, true}, {"off", []any{"https://example.org/path"}, true},
47+
{"internet", nil, true}, {"internet", []any{}, true}, {"internet", []any{"https://example.org"}, false},
48+
{"restricted", nil, false}, {"restricted", []any{}, false}, {"restricted", []any{"https://example.org"}, true},
49+
{"restricted", []any{"https://example.org", "https://example.org"}, true},
50+
{"restricted", []any{""}, false},
51+
{"off", eight, true}, {"restricted", eight, true},
52+
{"off", append(eight, "https://example.org"), false},
53+
{"restricted", append(eight, "https://example.org"), false},
54+
} {
55+
value := map[string]any{"browser_network_access": tc.mode, "workspace_id": "workspace-a", "revision": 1,
56+
"version": "browser_network_access.v1", "expected_revision": 1, "replayed": false, "for_next_run": false}
57+
if name == "BrowserNetworkAccessRequestView" || name == "WorkspaceBrowserNetworkAccessRequestView" {
58+
delete(value, "workspace_id")
59+
delete(value, "revision")
60+
delete(value, "replayed")
61+
delete(value, "for_next_run")
62+
} else {
63+
delete(value, "expected_revision")
64+
if name == "BrowserNetworkPreference" {
65+
delete(value, "version")
66+
delete(value, "replayed")
67+
delete(value, "for_next_run")
68+
}
69+
}
70+
if tc.origins != nil {
71+
value["browser_origins"] = tc.origins
72+
}
73+
if err := schema.Validate(value); (err == nil) != tc.valid {
74+
t.Fatalf("%s origins=%v: schema validation=%v, want valid=%t", tc.mode, tc.origins, err, tc.valid)
75+
}
76+
}
77+
})
78+
}
79+
}

‎internal/httpapi/openapi.go‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2854,6 +2854,14 @@ func (r *openAPISchemaRegistry) objectSchema(valueType reflect.Type) map[string]
28542854
if len(required) != 0 {
28552855
schema["required"] = required
28562856
}
2857+
if browserNetworkAccessSchema(metadataTypeName) {
2858+
schema["if"] = map[string]any{"properties": map[string]any{"browser_network_access": map[string]any{"const": "restricted"}}, "required": []string{"browser_network_access"}}
2859+
schema["then"] = map[string]any{"required": []string{"browser_origins"}, "properties": map[string]any{"browser_origins": map[string]any{"minItems": 1}}}
2860+
schema["else"] = map[string]any{
2861+
"if": map[string]any{"properties": map[string]any{"browser_network_access": map[string]any{"const": "internet"}}, "required": []string{"browser_network_access"}},
2862+
"then": map[string]any{"properties": map[string]any{"browser_origins": map[string]any{"maxItems": 0}}},
2863+
}
2864+
}
28572865
if metadataTypeName == "ThreadTurnControlRequestView" {
28582866
alternatives := []any{
28592867
map[string]any{"required": []string{"content"}, "properties": map[string]any{"content": map[string]any{"type": "string", "minLength": 1}}},
@@ -2866,6 +2874,15 @@ func (r *openAPISchemaRegistry) objectSchema(valueType reflect.Type) map[string]
28662874
return schema
28672875
}
28682876

2877+
func browserNetworkAccessSchema(typeName string) bool {
2878+
switch typeName {
2879+
case "BrowserNetworkAccessRequestView", "WorkspaceBrowserNetworkAccessRequestView", "BrowserNetworkAccessSelection", "BrowserNetworkPreference":
2880+
return true
2881+
default:
2882+
return false
2883+
}
2884+
}
2885+
28692886
func threadActivityTypedDetailSchema(properties map[string]any) map[string]any {
28702887
branches := []struct {
28712888
kind, field string
@@ -2915,6 +2932,13 @@ func jsonField(field reflect.StructField) (string, bool, bool) {
29152932
}
29162933

29172934
func applyOpenAPIFieldMetadata(typeName string, fieldName string, schema map[string]any) {
2935+
if browserNetworkAccessSchema(typeName) && fieldName == "browser_origins" {
2936+
schema["maxItems"] = browserruntime.MaxAgentBrowserScopeOrigins
2937+
schema["description"] = "At most eight HTTP(S) targets, canonicalized to sorted, deduplicated scheme/host/port origins. Restricted access requires at least one origin; Internet access requires an empty or omitted list. Off may retain inactive origins. Each target must be valid UTF-8 and fit within 4096 UTF-8 bytes both after trimming and after URL canonicalization; this byte limit is enforced by the server, not JSON Schema maxLength."
2938+
if items, ok := schema["items"].(map[string]any); ok {
2939+
items["minLength"] = 1
2940+
}
2941+
}
29182942
if typeName == "ThreadReplyUpdatesView" {
29192943
switch fieldName {
29202944
case "data_store_id":

0 commit comments

Comments
 (0)