@adhd/apigen-python-env 0.1.5 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (18) hide show
  1. package/CHANGELOG.md +8 -0
  2. package/index.js +6 -6
  3. package/index.mjs +56 -53
  4. package/lib/python-env.d.ts +14 -4
  5. package/package.json +2 -2
  6. package/python/apigen_logical.py +628 -0
  7. package/python/apigen_python/__init__.py +1 -0
  8. package/python/apigen_python/errors.py +99 -0
  9. package/python/apigen_python/extractor.py +578 -0
  10. package/python/apigen_python/flask_server.py +748 -0
  11. package/python/apigen_python/gateway_adapter.py +260 -0
  12. package/python/apigen_python/grpc_server.py +954 -0
  13. package/python/apigen_python/plugin_echo.py +100 -0
  14. package/python/apigen_python/runtime.py +228 -0
  15. package/python/apigen_python/validator.py +135 -0
  16. package/python/conformance_vectors.json +865 -0
  17. package/python/pyproject.toml +59 -0
  18. package/python/run_tests.py +2118 -0
package/python/conformance_vectors.json ADDED
@@ -0,0 +1,865 @@
1
+ {
2
+ "DESCRIPTOR_VECTORS": [
3
+ {
4
+ "id": "descriptor.roundtrip.1",
5
+ "description": "A complete Operation round-trips through JSON serialization losslessly",
6
+ "input": {
7
+ "host": "ts",
8
+ "kind": "action",
9
+ "async": true,
10
+ "streaming": false,
11
+ "safe": false,
12
+ "input": {
13
+ "type": "object",
14
+ "properties": {
15
+ "bytes": {
16
+ "type": "number"
17
+ },
18
+ "precision": {
19
+ "type": "number"
20
+ }
21
+ },
22
+ "required": [
23
+ "bytes"
24
+ ]
25
+ },
26
+ "output": {
27
+ "type": "string"
28
+ },
29
+ "envelope": {
30
+ "type": "object",
31
+ "properties": {
32
+ "session": {
33
+ "type": "string"
34
+ }
35
+ },
36
+ "required": [
37
+ "session"
38
+ ]
39
+ },
40
+ "typeText": {
41
+ "lang": "ts",
42
+ "input": "{ bytes: number; precision?: number }",
43
+ "output": "string"
44
+ },
45
+ "id": "transform/humanize/humanize-bytes",
46
+ "namespace": {
47
+ "raw": "transform",
48
+ "words": [
49
+ "transform"
50
+ ]
51
+ },
52
+ "path": [
53
+ {
54
+ "raw": "humanize",
55
+ "words": [
56
+ "humanize"
57
+ ]
58
+ },
59
+ {
60
+ "raw": "humanizeBytes",
61
+ "words": [
62
+ "humanize",
63
+ "bytes"
64
+ ]
65
+ }
66
+ ]
67
+ }
68
+ },
69
+ {
70
+ "id": "descriptor.roundtrip.2",
71
+ "description": "typeText: null is preserved (not dropped or coerced)",
72
+ "input": {
73
+ "host": "ts",
74
+ "kind": "action",
75
+ "async": false,
76
+ "streaming": false,
77
+ "safe": false,
78
+ "input": {
79
+ "type": "object",
80
+ "properties": {}
81
+ },
82
+ "output": {
83
+ "type": "object"
84
+ },
85
+ "envelope": {},
86
+ "typeText": null,
87
+ "id": "transform/ping",
88
+ "namespace": {
89
+ "raw": "transform",
90
+ "words": [
91
+ "transform"
92
+ ]
93
+ },
94
+ "path": [
95
+ {
96
+ "raw": "ping",
97
+ "words": [
98
+ "ping"
99
+ ]
100
+ }
101
+ ]
102
+ }
103
+ },
104
+ {
105
+ "id": "descriptor.roundtrip.3",
106
+ "description": "Empty $defs in input schema is preserved",
107
+ "input": {
108
+ "host": "ts",
109
+ "kind": "action",
110
+ "async": false,
111
+ "streaming": false,
112
+ "safe": false,
113
+ "input": {
114
+ "type": "object",
115
+ "$defs": {},
116
+ "properties": {}
117
+ },
118
+ "output": {
119
+ "type": "object"
120
+ },
121
+ "envelope": {},
122
+ "typeText": null,
123
+ "id": "transform/noop",
124
+ "namespace": {
125
+ "raw": "transform",
126
+ "words": [
127
+ "transform"
128
+ ]
129
+ },
130
+ "path": [
131
+ {
132
+ "raw": "noop",
133
+ "words": [
134
+ "noop"
135
+ ]
136
+ }
137
+ ]
138
+ }
139
+ }
140
+ ],
141
+ "NAMING_VECTORS": [
142
+ {
143
+ "id": "naming.verb.1",
144
+ "description": "safe=false → HTTP verb is POST",
145
+ "op": {
146
+ "host": "ts",
147
+ "kind": "action",
148
+ "async": false,
149
+ "streaming": false,
150
+ "safe": false,
151
+ "input": {
152
+ "type": "object",
153
+ "properties": {}
154
+ },
155
+ "output": {
156
+ "type": "object"
157
+ },
158
+ "envelope": {},
159
+ "typeText": null,
160
+ "id": "transform/humanize/humanize-bytes",
161
+ "namespace": {
162
+ "raw": "transform",
163
+ "words": [
164
+ "transform"
165
+ ]
166
+ },
167
+ "path": [
168
+ {
169
+ "raw": "humanize",
170
+ "words": [
171
+ "humanize"
172
+ ]
173
+ },
174
+ {
175
+ "raw": "humanizeBytes",
176
+ "words": [
177
+ "humanize",
178
+ "bytes"
179
+ ]
180
+ }
181
+ ]
182
+ },
183
+ "expected": {
184
+ "httpVerb": "POST"
185
+ }
186
+ },
187
+ {
188
+ "id": "naming.verb.2",
189
+ "description": "safe=true → HTTP verb is GET",
190
+ "op": {
191
+ "host": "ts",
192
+ "kind": "action",
193
+ "async": false,
194
+ "streaming": false,
195
+ "safe": true,
196
+ "input": {
197
+ "type": "object",
198
+ "properties": {}
199
+ },
200
+ "output": {
201
+ "type": "object"
202
+ },
203
+ "envelope": {},
204
+ "typeText": null,
205
+ "id": "transform/humanize/humanize-bytes-safe",
206
+ "namespace": {
207
+ "raw": "transform",
208
+ "words": [
209
+ "transform"
210
+ ]
211
+ },
212
+ "path": [
213
+ {
214
+ "raw": "humanize",
215
+ "words": [
216
+ "humanize"
217
+ ]
218
+ },
219
+ {
220
+ "raw": "humanizeBytes",
221
+ "words": [
222
+ "humanize",
223
+ "bytes"
224
+ ]
225
+ }
226
+ ]
227
+ },
228
+ "expected": {
229
+ "httpVerb": "GET"
230
+ }
231
+ },
232
+ {
233
+ "id": "naming.verb.NEGATIVE",
234
+ "description": "safe=false does NOT produce GET (negative control)",
235
+ "op": {
236
+ "host": "ts",
237
+ "kind": "action",
238
+ "async": false,
239
+ "streaming": false,
240
+ "safe": false,
241
+ "input": {
242
+ "type": "object",
243
+ "properties": {}
244
+ },
245
+ "output": {
246
+ "type": "object"
247
+ },
248
+ "envelope": {},
249
+ "typeText": null,
250
+ "id": "transform/humanize/humanize-bytes",
251
+ "namespace": {
252
+ "raw": "transform",
253
+ "words": [
254
+ "transform"
255
+ ]
256
+ },
257
+ "path": [
258
+ {
259
+ "raw": "humanize",
260
+ "words": [
261
+ "humanize"
262
+ ]
263
+ },
264
+ {
265
+ "raw": "humanizeBytes",
266
+ "words": [
267
+ "humanize",
268
+ "bytes"
269
+ ]
270
+ }
271
+ ]
272
+ },
273
+ "expected": {
274
+ "httpVerbIsNot": "GET"
275
+ }
276
+ },
277
+ {
278
+ "id": "naming.collision.1",
279
+ "description": "Two ids with identical path tokenization → CollisionDetectedError",
280
+ "ops": [
281
+ {
282
+ "host": "ts",
283
+ "kind": "action",
284
+ "async": false,
285
+ "streaming": false,
286
+ "safe": false,
287
+ "input": {
288
+ "type": "object",
289
+ "properties": {}
290
+ },
291
+ "output": {
292
+ "type": "object"
293
+ },
294
+ "envelope": {},
295
+ "typeText": null,
296
+ "id": "auth/session",
297
+ "namespace": {
298
+ "raw": "auth",
299
+ "words": [
300
+ "auth"
301
+ ]
302
+ },
303
+ "path": [
304
+ {
305
+ "raw": "session",
306
+ "words": [
307
+ "session"
308
+ ]
309
+ }
310
+ ]
311
+ },
312
+ {
313
+ "host": "ts",
314
+ "kind": "action",
315
+ "async": false,
316
+ "streaming": false,
317
+ "safe": false,
318
+ "input": {
319
+ "type": "object",
320
+ "properties": {}
321
+ },
322
+ "output": {
323
+ "type": "object"
324
+ },
325
+ "envelope": {},
326
+ "typeText": null,
327
+ "id": "auth/login",
328
+ "namespace": {
329
+ "raw": "auth",
330
+ "words": [
331
+ "auth"
332
+ ]
333
+ },
334
+ "path": [
335
+ {
336
+ "raw": "session",
337
+ "words": [
338
+ "session"
339
+ ]
340
+ }
341
+ ]
342
+ }
343
+ ],
344
+ "expected": {
345
+ "collision": true
346
+ }
347
+ },
348
+ {
349
+ "id": "naming.collision.2",
350
+ "description": "Distinct ops do NOT trigger collision",
351
+ "ops": [
352
+ {
353
+ "host": "ts",
354
+ "kind": "action",
355
+ "async": false,
356
+ "streaming": false,
357
+ "safe": false,
358
+ "input": {
359
+ "type": "object",
360
+ "properties": {}
361
+ },
362
+ "output": {
363
+ "type": "object"
364
+ },
365
+ "envelope": {},
366
+ "typeText": null,
367
+ "id": "auth/session",
368
+ "namespace": {
369
+ "raw": "auth",
370
+ "words": [
371
+ "auth"
372
+ ]
373
+ },
374
+ "path": [
375
+ {
376
+ "raw": "session",
377
+ "words": [
378
+ "session"
379
+ ]
380
+ }
381
+ ]
382
+ },
383
+ {
384
+ "host": "ts",
385
+ "kind": "action",
386
+ "async": false,
387
+ "streaming": false,
388
+ "safe": false,
389
+ "input": {
390
+ "type": "object",
391
+ "properties": {}
392
+ },
393
+ "output": {
394
+ "type": "object"
395
+ },
396
+ "envelope": {},
397
+ "typeText": null,
398
+ "id": "auth/login",
399
+ "namespace": {
400
+ "raw": "auth",
401
+ "words": [
402
+ "auth"
403
+ ]
404
+ },
405
+ "path": [
406
+ {
407
+ "raw": "login",
408
+ "words": [
409
+ "login"
410
+ ]
411
+ }
412
+ ]
413
+ }
414
+ ],
415
+ "expected": {
416
+ "collision": false
417
+ }
418
+ },
419
+ {
420
+ "id": "naming.collision.NEGATIVE",
421
+ "description": "Non-colliding set must NOT throw (negative control)",
422
+ "ops": [
423
+ {
424
+ "host": "ts",
425
+ "kind": "action",
426
+ "async": false,
427
+ "streaming": false,
428
+ "safe": false,
429
+ "input": {
430
+ "type": "object",
431
+ "properties": {}
432
+ },
433
+ "output": {
434
+ "type": "object"
435
+ },
436
+ "envelope": {},
437
+ "typeText": null,
438
+ "id": "auth/session",
439
+ "namespace": {
440
+ "raw": "auth",
441
+ "words": [
442
+ "auth"
443
+ ]
444
+ },
445
+ "path": [
446
+ {
447
+ "raw": "session",
448
+ "words": [
449
+ "session"
450
+ ]
451
+ }
452
+ ]
453
+ },
454
+ {
455
+ "host": "ts",
456
+ "kind": "action",
457
+ "async": false,
458
+ "streaming": false,
459
+ "safe": false,
460
+ "input": {
461
+ "type": "object",
462
+ "properties": {}
463
+ },
464
+ "output": {
465
+ "type": "object"
466
+ },
467
+ "envelope": {},
468
+ "typeText": null,
469
+ "id": "auth/login",
470
+ "namespace": {
471
+ "raw": "auth",
472
+ "words": [
473
+ "auth"
474
+ ]
475
+ },
476
+ "path": [
477
+ {
478
+ "raw": "login",
479
+ "words": [
480
+ "login"
481
+ ]
482
+ }
483
+ ]
484
+ }
485
+ ],
486
+ "expected": {
487
+ "collision": false
488
+ }
489
+ }
490
+ ],
491
+ "ENVELOPE_VECTORS": [
492
+ {
493
+ "id": "envelope.binding.auth.session",
494
+ "description": "(auth, session) → correct carrier key for all transports",
495
+ "pluginId": "auth",
496
+ "field": "session",
497
+ "expected": {
498
+ "httpHeader": "x-auth-session",
499
+ "grpcMeta": "x-auth-session",
500
+ "mcpMetaKey": "x-auth-session",
501
+ "cliFlag": "--auth-session",
502
+ "cliEnvVar": "APIGEN_AUTH_SESSION"
503
+ }
504
+ },
505
+ {
506
+ "id": "envelope.binding.adhd.trace_id",
507
+ "description": "(adhd, trace-id) → correct carrier key for all transports",
508
+ "pluginId": "adhd",
509
+ "field": "trace-id",
510
+ "expected": {
511
+ "httpHeader": "x-adhd-trace-id",
512
+ "grpcMeta": "x-adhd-trace-id",
513
+ "mcpMetaKey": "x-adhd-trace-id",
514
+ "cliFlag": "--adhd-trace-id",
515
+ "cliEnvVar": "APIGEN_TRACE_ID"
516
+ }
517
+ },
518
+ {
519
+ "id": "envelope.binding.rate.limit",
520
+ "description": "(rate, limit) → correct carrier key for all transports",
521
+ "pluginId": "rate",
522
+ "field": "limit",
523
+ "expected": {
524
+ "httpHeader": "x-rate-limit",
525
+ "grpcMeta": "x-rate-limit",
526
+ "mcpMetaKey": "x-rate-limit",
527
+ "cliFlag": "--rate-limit",
528
+ "cliEnvVar": "APIGEN_RATE_LIMIT"
529
+ }
530
+ }
531
+ ],
532
+ "ERROR_MAPPING_VECTORS": [
533
+ {
534
+ "id": "error.map.invalid_argument",
535
+ "code": "invalid_argument",
536
+ "expected": {
537
+ "http": 400,
538
+ "grpc": "INVALID_ARGUMENT",
539
+ "cli": 2,
540
+ "mcp": "error"
541
+ }
542
+ },
543
+ {
544
+ "id": "error.map.unauthenticated",
545
+ "code": "unauthenticated",
546
+ "expected": {
547
+ "http": 401,
548
+ "grpc": "UNAUTHENTICATED",
549
+ "cli": 3,
550
+ "mcp": "error"
551
+ }
552
+ },
553
+ {
554
+ "id": "error.map.permission_denied",
555
+ "code": "permission_denied",
556
+ "expected": {
557
+ "http": 403,
558
+ "grpc": "PERMISSION_DENIED",
559
+ "cli": 3,
560
+ "mcp": "error"
561
+ }
562
+ },
563
+ {
564
+ "id": "error.map.not_found",
565
+ "code": "not_found",
566
+ "expected": {
567
+ "http": 404,
568
+ "grpc": "NOT_FOUND",
569
+ "cli": 4,
570
+ "mcp": "error"
571
+ }
572
+ },
573
+ {
574
+ "id": "error.map.internal",
575
+ "code": "internal",
576
+ "expected": {
577
+ "http": 500,
578
+ "grpc": "INTERNAL",
579
+ "cli": 1,
580
+ "mcp": "error"
581
+ }
582
+ }
583
+ ],
584
+ "VALIDATION_VECTORS": [
585
+ {
586
+ "id": "validation.extra-properties",
587
+ "description": "additionalProperties not restricted — extra keys pass schema but may cause dispatch errors",
588
+ "schema": {
589
+ "type": "object",
590
+ "properties": {
591
+ "userId": {
592
+ "type": "string"
593
+ }
594
+ },
595
+ "required": [
596
+ "userId"
597
+ ]
598
+ },
599
+ "schemaValidValue": {
600
+ "userId": "abc",
601
+ "unexpectedField": "injection"
602
+ },
603
+ "domainNote": "An unexpected field passes the schema but may be ignored or cause a typed dispatch error in strict hosts (Rust/Go)."
604
+ },
605
+ {
606
+ "id": "validation.number-precision",
607
+ "description": "A JSON number within the schema range but beyond JS safe integer boundary",
608
+ "schema": {
609
+ "type": "object",
610
+ "properties": {
611
+ "amount": {
612
+ "type": "integer"
613
+ }
614
+ },
615
+ "required": [
616
+ "amount"
617
+ ]
618
+ },
619
+ "schemaValidValue": {
620
+ "amount": 9007199254740992
621
+ },
622
+ "domainNote": "Exceeds Number.MAX_SAFE_INTEGER; JSON.parse silently rounds it. SPEC §4 mandates int64 as string-encoded for 64-bit integers; this proves the validator alone cannot catch the precision loss."
623
+ },
624
+ {
625
+ "id": "validation.date-string",
626
+ "description": "A date-format string is schema-valid but semantically wrong",
627
+ "schema": {
628
+ "type": "object",
629
+ "properties": {
630
+ "at": {
631
+ "type": "string",
632
+ "format": "date-time"
633
+ }
634
+ },
635
+ "required": [
636
+ "at"
637
+ ]
638
+ },
639
+ "schemaValidValue": {
640
+ "at": "2099-02-30T00:00:00Z"
641
+ },
642
+ "domainNote": "Standard AJV does not validate date-time values by default; Feb 30 passes schema validation but is a semantically invalid date."
643
+ },
644
+ {
645
+ "id": "validation.option-vs-missing",
646
+ "description": "An Option/nullable field being null passes where a domain function expects presence",
647
+ "schema": {
648
+ "type": "object",
649
+ "properties": {
650
+ "user": {
651
+ "oneOf": [
652
+ {
653
+ "type": "object",
654
+ "properties": {
655
+ "id": {
656
+ "type": "string"
657
+ }
658
+ }
659
+ },
660
+ {
661
+ "type": "null"
662
+ }
663
+ ]
664
+ }
665
+ },
666
+ "required": [
667
+ "user"
668
+ ]
669
+ },
670
+ "schemaValidValue": {
671
+ "user": null
672
+ },
673
+ "domainNote": "null satisfies the oneOf schema, but a domain function that destructures user.id will throw at runtime — validation passed, dispatch fails."
674
+ }
675
+ ],
676
+ "ENVELOPE_CASES": [
677
+ {
678
+ "pluginId": "auth",
679
+ "field": "session",
680
+ "expectedKey": "x-auth-session",
681
+ "expectedFlag": "--auth-session",
682
+ "expectedEnv": "APIGEN_AUTH_SESSION"
683
+ },
684
+ {
685
+ "pluginId": "adhd",
686
+ "field": "trace-id",
687
+ "expectedKey": "x-adhd-trace-id",
688
+ "expectedFlag": "--adhd-trace-id",
689
+ "expectedEnv": "APIGEN_TRACE_ID"
690
+ },
691
+ {
692
+ "pluginId": "rate",
693
+ "field": "limit",
694
+ "expectedKey": "x-rate-limit",
695
+ "expectedFlag": "--rate-limit",
696
+ "expectedEnv": "APIGEN_RATE_LIMIT"
697
+ }
698
+ ],
699
+ "LOGICAL_TYPE_VECTORS": [
700
+ {
701
+ "id": "logical.date-time.roundtrip",
702
+ "logicalType": "date-time",
703
+ "schema": {
704
+ "type": "string",
705
+ "format": "date-time"
706
+ },
707
+ "seed": {
708
+ "$construct": "date-time",
709
+ "args": [
710
+ "2024-01-15T12:34:56.789Z"
711
+ ]
712
+ },
713
+ "wire": "2024-01-15T12:34:56.789Z",
714
+ "invariants": [
715
+ {
716
+ "pointer": "/epochMs",
717
+ "equals": 1705322096789
718
+ }
719
+ ],
720
+ "negativeControl": {
721
+ "mutate": "wire",
722
+ "to": "2024-01-15T12:34:56.789+05:30"
723
+ }
724
+ },
725
+ {
726
+ "id": "logical.int64.roundtrip",
727
+ "logicalType": "int64",
728
+ "schema": {
729
+ "type": "string",
730
+ "format": "int64"
731
+ },
732
+ "seed": "9007199254740993",
733
+ "wire": "9007199254740993",
734
+ "invariants": [
735
+ {
736
+ "pointer": "/bigintStr",
737
+ "equals": "9007199254740993"
738
+ }
739
+ ],
740
+ "negativeControl": {
741
+ "mutate": "wire",
742
+ "to": 9007199254740992
743
+ }
744
+ },
745
+ {
746
+ "id": "logical.decimal.roundtrip",
747
+ "logicalType": "decimal",
748
+ "schema": {
749
+ "type": "string",
750
+ "format": "decimal"
751
+ },
752
+ "seed": "123.456",
753
+ "wire": "123.456",
754
+ "invariants": [
755
+ {
756
+ "pointer": "/str",
757
+ "equals": "123.456"
758
+ }
759
+ ],
760
+ "negativeControl": {
761
+ "mutate": "wire",
762
+ "to": 123.456
763
+ }
764
+ },
765
+ {
766
+ "id": "logical.byte.roundtrip",
767
+ "logicalType": "byte",
768
+ "schema": {
769
+ "type": "string",
770
+ "format": "byte"
771
+ },
772
+ "seed": {
773
+ "$construct": "byte",
774
+ "args": [
775
+ [
776
+ 72,
777
+ 101,
778
+ 108,
779
+ 108,
780
+ 111
781
+ ]
782
+ ]
783
+ },
784
+ "wire": "SGVsbG8=",
785
+ "invariants": [
786
+ {
787
+ "pointer": "/utf8",
788
+ "equals": "Hello"
789
+ }
790
+ ],
791
+ "negativeControl": {
792
+ "mutate": "wire",
793
+ "to": "SGVs_G8="
794
+ }
795
+ },
796
+ {
797
+ "id": "logical.uuid.roundtrip",
798
+ "logicalType": "uuid",
799
+ "schema": {
800
+ "type": "string",
801
+ "format": "uuid"
802
+ },
803
+ "seed": "550e8400-e29b-41d4-a716-446655440000",
804
+ "wire": "550e8400-e29b-41d4-a716-446655440000",
805
+ "invariants": [
806
+ {
807
+ "pointer": "/value",
808
+ "equals": "550e8400-e29b-41d4-a716-446655440000"
809
+ }
810
+ ],
811
+ "negativeControl": {
812
+ "mutate": "wire",
813
+ "to": "550E8400-E29B-41D4-A716-446655440000"
814
+ }
815
+ },
816
+ {
817
+ "id": "logical.number-special.nan",
818
+ "logicalType": "number-special",
819
+ "schema": {
820
+ "type": "number"
821
+ },
822
+ "seed": {
823
+ "$construct": "number-special",
824
+ "args": [
825
+ "NaN"
826
+ ]
827
+ },
828
+ "wire": "NaN",
829
+ "invariants": [
830
+ {
831
+ "pointer": "/isNaN",
832
+ "equals": true
833
+ }
834
+ ],
835
+ "negativeControl": {
836
+ "mutate": "wire",
837
+ "to": null
838
+ }
839
+ },
840
+ {
841
+ "id": "logical.number-special.infinity",
842
+ "logicalType": "number-special",
843
+ "schema": {
844
+ "type": "number"
845
+ },
846
+ "seed": {
847
+ "$construct": "number-special",
848
+ "args": [
849
+ "Infinity"
850
+ ]
851
+ },
852
+ "wire": "Infinity",
853
+ "invariants": [
854
+ {
855
+ "pointer": "/isFinite",
856
+ "equals": false
857
+ }
858
+ ],
859
+ "negativeControl": {
860
+ "mutate": "wire",
861
+ "to": null
862
+ }
863
+ }
864
+ ]
865
+ }