lawspec 0.20.0 → 0.21.0

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.
package/core.wasm CHANGED
Binary file
package/core_jsffi.js CHANGED
@@ -98,8 +98,8 @@ ZC20ZCghczminternalZCGHCziInternalziWasmziPrimziExportsZC: ($1) => {$1.throwTo =
98
98
  ZC21ZCghczminternalZCGHCziInternalziWasmziPrimziExportsZC: ($1,$2) => {$1.throwTo = (err) => __exports.rts_promiseThrowTo($2, err);},
99
99
  ZC22ZCghczminternalZCGHCziInternalziWasmziPrimziExportsZC: () => {let res, rej; const p = new Promise((resolve, reject) => { res = resolve; rej = reject; }); p.resolve = res; p.reject = rej; return p;},
100
100
  ZC0ZCghczminternalZCGHCziInternalziWasmziPrimziTypesZC: ($1) => (`${$1.stack ? $1.stack : $1}`),
101
- ZC1ZCghczminternalZCGHCziInternalziWasmziPrimziTypesZC: ($1,$2) => ((new TextDecoder('utf-8', {fatal: true})).decode(new Uint8Array(__exports.memory.buffer, $1, $2))),
102
- ZC2ZCghczminternalZCGHCziInternalziWasmziPrimziTypesZC: ($1,$2,$3) => ((new TextEncoder()).encodeInto($1, new Uint8Array(__exports.memory.buffer, $2, $3)).written),
101
+ ZC1ZCghczminternalZCGHCziInternalziWasmziPrimziTypesZC: ($1,$2) => ((new TextDecoder('utf-8', {fatal: true})).decode(new Uint8Array(__exports.memory.buffer, $1 >>> 0, $2))),
102
+ ZC2ZCghczminternalZCGHCziInternalziWasmziPrimziTypesZC: ($1,$2,$3) => ((new TextEncoder()).encodeInto($1, new Uint8Array(__exports.memory.buffer, $2 >>> 0, $3)).written),
103
103
  ZC3ZCghczminternalZCGHCziInternalziWasmziPrimziTypesZC: ($1) => ($1.length),
104
104
  ZC4ZCghczminternalZCGHCziInternalziWasmziPrimziTypesZC: ($1) => {try { __ghc_wasm_jsffi_finalization_registry.unregister($1); } catch {}},
105
105
  ZC18ZCghczminternalZCGHCziInternalziWasmziPrimziImportsZC: ($1,$2) => ($1.then(() => __exports.rts_promiseResolveUnit($2), err => __exports.rts_promiseReject($2, err))),
@@ -0,0 +1,103 @@
1
+ unit example.abilities
2
+
3
+ -- Dependencies are abilities. An ability names operations, the way a
4
+ -- signature names a function; a handler gives them meaning. Code that uses
5
+ -- Gateway says so, and every law about it holds for every lawful handler:
6
+ -- the native one written by hand, and each spec handler below.
7
+
8
+ type Payment is | Approved cents :: Int32 | Declined end
9
+ type Receipt is Receipt cents :: Int32 end
10
+ type PaymentError is | Refused | TooLarge end
11
+
12
+ -- A payment gateway. Its laws are obligations on every handler.
13
+ ability Gateway is
14
+ authorize :: Int32 -> Payment
15
+ capture :: Int32 -> Receipt
16
+ fee :: Int32
17
+ laws
18
+ law `a receipt is for the amount captured` is
19
+ definition is `for all` (cents :: Int32) . capture cents = Receipt cents end
20
+ end
21
+ law `an approval is for the amount asked` is
22
+ definition is
23
+ `for all` (cents :: Int32) .
24
+ (match authorize cents with
25
+ | Approved approved -> approved == cents
26
+ | Declined -> true
27
+ end) = true
28
+ end
29
+ end
30
+ law `the fee is never negative` is
31
+ definition is fee >= 0 end
32
+ end
33
+ end
34
+
35
+ -- A fake for tests: it approves small amounts.
36
+ handler fakeGateway for Gateway is
37
+ authorize cents is if cents <= 10000 then Approved cents else Declined end
38
+ capture cents is Receipt cents end
39
+ fee is 30 end
40
+ end
41
+
42
+ -- A handler with state: it keeps every amount it captured.
43
+ handler keepingGateway for Gateway with state captured :: List Int32 start [] is
44
+ authorize cents is Approved cents end
45
+ capture cents is ~captured := Cons cents captured; Receipt cents end
46
+ fee is 0 end
47
+ end
48
+
49
+ -- A checked definition that uses Gateway. Its row, {Gateway}, is inferred.
50
+ definition checkout (cents :: Int32) :: Bool is
51
+ match authorize cents with
52
+ | Approved amount -> (match capture amount with | Receipt paid -> paid == cents end)
53
+ | Declined -> false
54
+ end
55
+ end
56
+
57
+ -- A native adapter that uses Gateway: it gets a handler as its first
58
+ -- argument.
59
+ charge :: Int32 -> Bool uses Gateway
60
+
61
+ -- A definition that can fail says what it fails with.
62
+ definition pay (cents :: Int32) :: Receipt uses Gateway fails with PaymentError is
63
+ if cents > 100000 then raise TooLarge else
64
+ match authorize cents with
65
+ | Approved amount -> capture amount
66
+ | Declined -> raise Refused
67
+ end
68
+ end
69
+
70
+ -- Counting calls is part of the claim, so the law names a recording
71
+ -- handler. Which gateway it records is left to the harness: each lawful one.
72
+ law `checkout captures once, and only when it succeeds` using recording Gateway is
73
+ definition is
74
+ `for all` (cents :: Int32) .
75
+ (if checkout cents then calls of capture with (cents) == 1 else calls of capture == 0) = true
76
+ end
77
+ end
78
+
79
+ law `charge captures once, and only when it succeeds` using recording Gateway is
80
+ definition is
81
+ `for all` (cents :: Int32) .
82
+ (if charge cents then calls of capture with (cents) == 1 else calls of capture == 0) = true
83
+ end
84
+ end
85
+
86
+ -- This law needs the fake's limit, so the fake is part of the claim.
87
+ law `large payments fail` using fakeGateway is
88
+ definition is
89
+ `for all` (cents :: Int32 where cents > 100000) . prelude.attempt (pay cents) = Left TooLarge
90
+ end
91
+ end
92
+
93
+ law `a declined payment is refused` using fakeGateway is
94
+ definition is
95
+ `for all` (cents :: Int32 where cents > 10000 && cents <= 100000) .
96
+ prelude.attempt (pay cents) = Left Refused
97
+ end
98
+ end
99
+
100
+ -- Without `using`, a law runs under each lawful handler in turn.
101
+ law `the fee is small` is
102
+ definition is fee <= 100 end
103
+ end
@@ -0,0 +1,107 @@
1
+ unit example.shop
2
+
3
+ import example.abilities as payments
4
+
5
+ -- Abilities cross units: Gateway and its handlers come from
6
+ -- example.abilities. This unit adds two of its own.
7
+
8
+ -- A log. Its operation gives nothing back, so code calls it for its effect
9
+ -- and goes on with `;`.
10
+ ability Log is
11
+ note :: Text -> Unit
12
+ end
13
+
14
+ -- A log that keeps what it is told.
15
+ handler keptLog for Log with state lines :: List Text start [] is
16
+ note message is ~lines := Cons message lines; unitValue end
17
+ end
18
+
19
+ -- A store of one value, at any type. This unit uses it at two.
20
+ ability Store (a :: Type) is
21
+ load :: a
22
+ save :: a -> Unit
23
+ end
24
+
25
+ handler countStore for Store Int32 with state count :: Int32 start 0 is
26
+ load is count end
27
+ save value is ~count := value; unitValue end
28
+ end
29
+
30
+ handler nameStore for Store Text with state name :: Text start "" is
31
+ load is name end
32
+ save value is ~name := value; unitValue end
33
+ end
34
+
35
+ -- A meter whose readings are never negative: every handler owes that.
36
+ ability Meter is
37
+ reading :: (r :: Int32 where r >= 0)
38
+ end
39
+
40
+ handler fixedMeter for Meter is
41
+ reading is 7 end
42
+ end
43
+
44
+ -- A handler whose clauses use another ability: it notes each payment.
45
+ handler notingGateway for Gateway is
46
+ authorize cents is note "authorize"; Approved cents end
47
+ capture cents is note "capture"; Receipt cents end
48
+ fee is 0 end
49
+ end
50
+
51
+ -- Effects run in order: `a; b` runs a, then b; `let x = e in body` runs e
52
+ -- once and names its value.
53
+ definition buy (cents :: Int32) :: Bool uses Gateway, Log is
54
+ note "buying";
55
+ let approved = payments.checkout cents in
56
+ note "bought";
57
+ approved
58
+ end
59
+
60
+ -- handle ... with h end runs its body with h answering h's ability, so the
61
+ -- definition does not use that ability itself.
62
+ definition trial (cents :: Int32) :: Bool is
63
+ handle payments.checkout cents with fakeGateway end
64
+ end
65
+
66
+ definition remember (count :: Int32) :: Int32 uses Store Int32 is
67
+ save count; load
68
+ end
69
+
70
+ definition rename (name :: Text) :: Text uses Store Text is
71
+ save name; load
72
+ end
73
+
74
+ -- A native adapter that may fail. Its native code raises the failure
75
+ -- through the runtime's Fail.
76
+ refund :: Int32 -> Int32 uses Gateway fails with payments.PaymentError
77
+
78
+ law `trial approves small amounts` is
79
+ definition is
80
+ `for all` (cents :: Int32 where cents >= 0 && cents <= 10000) . trial cents = true
81
+ end
82
+ end
83
+
84
+ law `buying with a noting gateway approves small amounts` using notingGateway, keptLog is
85
+ definition is
86
+ `for all` (cents :: Int32 where cents >= 0 && cents <= 10000) . buy cents = true
87
+ end
88
+ end
89
+
90
+ law `a stored count comes back` is
91
+ definition is `for all` (count :: Int32) . remember count = count end
92
+ end
93
+
94
+ law `a stored name comes back` is
95
+ definition is `for all` (name :: Text) . rename name = name end
96
+ end
97
+
98
+ law `a reading is small` using fixedMeter is
99
+ definition is reading <= 100 end
100
+ end
101
+
102
+ law `refunds of large amounts fail` is
103
+ definition is
104
+ `for all` (cents :: Int32 where cents > 100000) .
105
+ prelude.attempt (refund cents) = Left payments.TooLarge
106
+ end
107
+ end
@@ -0,0 +1,121 @@
1
+ unit example.builtins
2
+
3
+ -- The built-in abilities: each unit is imported like any other, and each
4
+ -- ability's production handler is the runtime's default one.
5
+ import lawspec.time (Instant, advance)
6
+ import lawspec.randomness
7
+ import lawspec.host
8
+ import lawspec.logging (LogLevel)
9
+ import lawspec.concurrent
10
+
11
+ -- Time. A deadline is now plus a wait; instants move by durations and are
12
+ -- a duration apart.
13
+ definition deadline (wait :: Duration where wait <= 1h) :: Instant uses Clock is now + wait end
14
+
15
+ -- Under the virtual clock, time moves only when told to.
16
+ law `a deadline is as far off as the wait` using virtual clock is
17
+ definition is
18
+ `for all` (wait :: Duration where wait <= 1h) . (let d = deadline wait in d - now) = wait
19
+ end
20
+ end
21
+
22
+ law `advancing moves the virtual clock` using virtual clock is
23
+ definition is
24
+ `for all` (d :: Duration where d <= 1h) . (let a = now in advance d; let b = now in b - a) = d
25
+ end
26
+ end
27
+
28
+ -- Time in laws: temporal propositions check over the clock, so under the
29
+ -- virtual clock they are deterministic.
30
+ law `a deadline eventually passes` using virtual clock is
31
+ definition is
32
+ `for all` (wait :: Duration where wait <= 1s) . (let d = deadline wait in eventually within 2 s, now >= d) = true
33
+ end
34
+ end
35
+
36
+ law `nothing is late before its deadline` using virtual clock is
37
+ definition is (let d = deadline 3s in always within 2 s, now < d) = true end
38
+ end
39
+
40
+ -- A performance budget, measured on the real clock.
41
+ law `a deadline is quick to make` is
42
+ definition is `for all` (wait :: Duration where wait <= 1h) . deadline wait takes at most 500 ms end
43
+ example `an hour` is
44
+ wait = 1h
45
+ expect deadline wait takes at most 500 ms
46
+ end
47
+ end
48
+
49
+ -- A native adapter gets its handlers as arguments: here the real clock.
50
+ elapsed :: Int32 -> Duration uses Clock
51
+
52
+ law `elapsed time is never negative` is
53
+ definition is `for all` (n :: Int32 where n >= 0 && n <= 3) . elapsed n >= 0ms end
54
+ end
55
+
56
+ -- Random draws are reproducible: the same seed gives the same draws, on
57
+ -- every target.
58
+ definition roll (sides :: Int64 where sides >= 1) :: Integer uses Random is randomBelow sides + 1 end
59
+
60
+ law `a seed fixes the rolls` is
61
+ definition is
62
+ `for all` (sides :: Int64 where sides >= 1) .
63
+ handle roll sides with seededRandom end = handle roll sides with seededRandom end
64
+ end
65
+ example `the first roll from seed 0` is
66
+ sides = 6
67
+ expect handle roll sides with seededRandom end = 6
68
+ end
69
+ example `the first roll from seed 42` is
70
+ sides = 1000
71
+ expect handle roll sides with seededRandom 42 end = 78
72
+ end
73
+ end
74
+
75
+ law `rolls are on the die` using seeded random 42 is
76
+ definition is
77
+ `for all` (sides :: Int64 where sides >= 1) . (let r = roll sides in r >= 1 && r <= sides) = true
78
+ end
79
+ end
80
+
81
+ -- Secure draws come from SecureRandom, which a seeded source cannot answer.
82
+ token :: Int32 -> Bytes uses SecureRandom
83
+
84
+ law `a token has the length asked` is
85
+ definition is `for all` (n :: Int32 where n >= 0 && n <= 64) . prelude.length (token n) = n end
86
+ end
87
+
88
+ -- Files, the environment and ports.
89
+ definition remember (note :: Bytes) :: Maybe Bytes uses FileSystem is
90
+ writeBytes ".lawspec-note" note; let read = readBytes ".lawspec-note" in removePath ".lawspec-note"; read
91
+ end
92
+
93
+ law `a remembered note reads back` is
94
+ definition is `for all` (note :: Bytes) . remember note = Just note end
95
+ end
96
+
97
+ law `an empty environment has no variables` using emptyEnvironment is
98
+ definition is `for all` (name :: Text) . environmentVariable name = Nothing end
99
+ end
100
+
101
+ listening :: Int32 -> Bool uses Ports
102
+
103
+ law `a free port can be listened on` is
104
+ definition is `for all` (n :: Int32 where n >= 0 && n <= 2) . listening n = true end
105
+ end
106
+
107
+ -- Logs. A law that inspects what was logged records the log.
108
+ charge :: Int32 -> Bool uses Log
109
+
110
+ law `a charge is logged once` using recording Log is
111
+ definition is
112
+ `for all` (cents :: Int32 where cents >= 0 && cents <= 1000) .
113
+ (if charge cents then calls of logMessage == 1 else calls of logMessage == 0) = true
114
+ end
115
+ end
116
+
117
+ definition traced (n :: Int32) :: Int32 uses Trace, Async is traceEvent "traced"; pause; n end
118
+
119
+ law `tracing keeps the value` is
120
+ definition is `for all` (n :: Int32) . traced n = n end
121
+ end
@@ -0,0 +1,51 @@
1
+ unit example.crypto
2
+
3
+ -- Post-quantum cryptography by default: ML-KEM-768 key exchange, ML-DSA-65
4
+ -- signatures, SHA3-256, and AES-256-GCM. Their laws hold for every lawful
5
+ -- handler; the defaults are also checked against NIST's vectors.
6
+ import lawspec.crypto (ExchangeKeyPair, ExchangePublicKey, Encapsulated, SigningKeyPair)
7
+
8
+ -- A handshake from the building blocks. The server signs its exchange key
9
+ -- with its long-term key; the client checks the signature, encapsulates a
10
+ -- secret to the exchange key, and both sides derive the same AEAD key from
11
+ -- it. The client's message then crosses sealed.
12
+ definition handshake (message :: Bytes) (context :: Bytes) :: Maybe Bytes uses KeyExchange, Signature, Aead is
13
+ match signingKeyPair with
14
+ | SigningKeyPair verifying signing ->
15
+ (match exchangeKeyPair with
16
+ | ExchangeKeyPair public secret ->
17
+ (let offer = sign signing (valueOfExchangePublicKey public) in
18
+ if verify verifying (valueOfExchangePublicKey public) offer then
19
+ (match encapsulate public with
20
+ | Encapsulated sent shared ->
21
+ (let client = deriveAeadKey shared context in
22
+ let server = deriveAeadKey (decapsulate secret sent) context in
23
+ unseal server (seal client message context) context)
24
+ end)
25
+ else Nothing)
26
+ end)
27
+ end
28
+ end
29
+
30
+ law `a handshake carries the message` is
31
+ definition is `for all` (message :: Bytes) (context :: Bytes) . handshake message context = Just message end
32
+ end
33
+
34
+ -- A native adapter: a short fingerprint of a public key, from its SHA3-256
35
+ -- digest.
36
+ fingerprint :: Bytes -> Bytes uses Hash
37
+
38
+ law `a fingerprint is 8 bytes` is
39
+ definition is `for all` (key :: Bytes) . prelude.length (fingerprint key) = 8 end
40
+ end
41
+
42
+ law `a key has one fingerprint` is
43
+ definition is `for all` (key :: Bytes) . fingerprint key = fingerprint key end
44
+ end
45
+
46
+ -- A native adapter that seals with a fresh key and opens again.
47
+ roundTrip :: Bytes -> Bool uses Aead
48
+
49
+ law `sealed messages open` is
50
+ definition is `for all` (message :: Bytes) . roundTrip message = true end
51
+ end
@@ -1,5 +1,11 @@
1
1
  unit example.distribution
2
2
 
3
+ -- Nodes are secure: this import brings the secure network handler (node
4
+ -- identities, the post-quantum handshake, sealed frames) and its crypto
5
+ -- libraries. Without it, only the in-memory transport made for tests can
6
+ -- make a node.
7
+ import lawspec.network
8
+
3
9
  -- Distribution. Nodes reach each other's actors, channels and checked
4
10
  -- definitions over a transport: in memory (with faults, for testing), TCP or
5
11
  -- HTTP. Values cross in the canonical wire encoding, the same bytes on every
@@ -130,3 +136,26 @@ async remoteHandoffOnward :: Int32 -> Int64
130
136
  law `a channel end moved on twice` is
131
137
  definition is `for all` (x :: Int32) . remoteHandoffOnward x = 2 * x end
132
138
  end
139
+
140
+ -- The network is secure by default. Each node has an ML-DSA-65 identity;
141
+ -- the first frame between two nodes waits for a handshake (a signed
142
+ -- ML-KEM-768 exchange), and every frame then crosses sealed with
143
+ -- AES-256-GCM. A node on the in-memory transport made for tests can skip
144
+ -- it; no other transport can.
145
+ async sealedOnTheWire :: Int32 -> Bool
146
+
147
+ law `frames cross sealed by default` is
148
+ definition is `for all` (x :: Int32) . sealedOnTheWire x = true end
149
+ end
150
+
151
+ -- Every target computes the same handshake: from these seeds and this
152
+ -- ciphertext, the same hashes of the hello and welcome, the same session
153
+ -- key, and the same sealed frame. The fields are, in order: the two
154
+ -- identities' seeds, the ephemeral ML-KEM seed, the session, the two
155
+ -- addresses, the ciphertext, the nonce, the frame, then the expected hashes,
156
+ -- key and sealed record (dev/handshake-vector.py makes them).
157
+ handshakeAgrees :: Text -> Bool
158
+
159
+ law `the secure handshake agrees across targets` is
160
+ definition is handshakeAgrees "000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f 202122232425262728292a2b2c2d2e2f303132333435363738393a3b3c3d3e3f 404142434445464748494a4b4c4d4e4f505152535455565758595a5b5c5d5e5f606162636465666768696a6b6c6d6e6f707172737475767778797a7b7c7d7e7f 808182838485868788898a8b8c8d8e8f tcp://10.0.0.1:7000 tcp://10.0.0.2:7000 36ed31b7f151b4412fa0898659e567a9fe899394069c31ec9007f98bd63282609999cc959fe9a01b4e9a21d61a866da30cdfb2db3d533e3614a170941f668dbe14b0ed47843bd401f8c76d5c8bc030e33c25cabf09b8fd4e3bdb84fc0fe2d8f1b7fea58f9124cd315d94970a9a9677160ffc00cd22875a598904ddd45c5e94ebea8db52eddd181d50f89a577de6f2cb21836a9da82e68ccf61d7aa72576a9ed6355577af27522b4006af2148510c5e8c901aafca088990811e31791a4c71abb7d96c522ee2de83431dc6db6d13e6b8a8cf8656cb64cf8368b691344d07f3ab75814960f85671890e8ccf6a2cf6b82667ff9a4a09eb59f0168453bc45ade0fa1bf747db6c2179dc1173689897f1dd582f2737f3bc8b6f3b84fa5bda5f204ae845ee5124363cad0ad7a3827c46f3ba55458215b32e748fb075e146880c93e97ca8f0f6b5768ac08d19127a2038889352893f19daccb8a01607805492a3c429df462ee941a73fd396de512d8873e901764b2636e7b03c5562097db59e8e00b08a65667873fdfcff99c805aaf49871d282744ee26118c43186d408ac5a0105c80e2b640d0ba44250887721535d865b1425e193777f4e0967a4d74e17fb14c54befd35d7baadb2caad627bb88e739e8d87616a38ac38bdea36c8b0e6dca981dd7cd15846d4187e2e841d1f6ce704369fddf5957b8827a80c80b1f34f44bab0b48ef26a30486f228c2c023e50ec6fb61c1ced87ab11b41b1e30a7f1a30e2c67e78bffead095b3dfc69205965bf9133a8f3dcc7e074ebaed77fd9f009906228f216a12af663d248c871a3a4b728da3d9987e53416c492da03f9c8f3c6c702f082cfdf8a326268a8e7d3c59f54405eef85c6104207bec5685dab59fdfa94b88cd22a00c8b89a85f71fb09d500b62422fdfac9fc7112aa8f756c3a723d211eeb2081d8858e87b1f480fb4cf80d194527f883be6ff89e648884d62c5df6af29de4119efe1fd5546a120902daa9a087143233432942b828871a1f8ec50081312a3e5363315b5198a5f71849cd9541b4aaaeb956f30a1be583532b1810687f6900c85d05e6e9d066570306c5ced181d90807f85634f1cbed272e8614caa69ddb359862eec8ea23b8e3a741e45e730e1ac9f7832bf4fee8f0a41f77015d0e95394838964bb43032b085cf8af0abe20701c011086474b610fa25185b33e24ea7493f28cc60fd78e5598a612f5c62d14344fa6a08d23231b78830d92c1d816ce3d51f33316c76b7896d789fda34cae5e095e592e73b7c300e9fbeb87aef276c5b0d53e3c120bf204bf8a3c5823e7318bf3e7da8e1abb590f0012a10882f49be91c496b000c28a067014ff1e6734f556b4918f2661faeef5783fbea9ba50340b6532edabf4d89b4113c72e6f92e085fb499a93335d03f616a1ecb5258713e0903c475e043486c78d16d0a4014ec1a065a87ac940e909df94d53109d109bd5b235b0c05b5b81fe202cebabd7cec50e434300eff7b75d910471f8bd400f04a7ffb814051c8b15fe7b7 c8c9cacbcccdcecfd0d1d2d3 046368616e05656e642d33137463703a2f2f31302e302e302e313a373030300e0300022a da31284386e2b951348bda30557cf4b5abb4ad9a1ac15582e99c3b938573a254 9c78ba836e9dcaf2845dceaa7a02c9aad0fe0fd29bb9a5b948635c65aa4b2676 c595a58a85aebe6fb8009a0ca6afc9eb614c7ab4711c08c4f7d34c38420c4abd 4c53010310808182838485868788898a8b8c8d8e8f0040c8c9cacbcccdcecfd0d1d2d314713b317e0cd4b10f4d5b885bc8bc1fa7aae4f824a30442ed569d3eab22fcce44c274bd139e84e8a9960d14a17722544ee187c1" = true end
161
+ end
@@ -0,0 +1,96 @@
1
+ unit example.failures
2
+
3
+ -- Typed failures. A definition that can fail says what it fails with, and a
4
+ -- law says which failure it expects: `fails with` takes a constructor
5
+ -- pattern, where _ matches any field, and may also check the failure's
6
+ -- message.
7
+
8
+ type Decision is
9
+ | Approve
10
+ | Decline reason :: Text
11
+ | Block
12
+ end
13
+
14
+ type PaymentError is
15
+ | Declined message :: Text
16
+ | Blocked
17
+ | TooLarge limit :: Int32
18
+ end
19
+
20
+ -- The payment provider decides; its native handler is written by hand.
21
+ ability Gateway is
22
+ decide :: Int32 -> Decision
23
+ end
24
+
25
+ definition charge (cents :: Int32) :: Int32 uses Gateway fails with PaymentError is
26
+ if cents > 100000 then raise (TooLarge 100000) else
27
+ match decide cents with
28
+ | Approve -> cents
29
+ | Decline reason -> raise (Declined reason)
30
+ | Block -> raise Blocked
31
+ end
32
+ end
33
+
34
+ law `large charges fail as too large` is
35
+ definition is
36
+ `for all` (cents :: Int32 where cents > 100000) . charge cents fails with TooLarge 100000
37
+ end
38
+ end
39
+
40
+ law `odd amounts are declined, and say why` is
41
+ definition is
42
+ `for all` (cents :: Int32 where cents >= 0 && cents <= 100000 && prelude.rem cents 2 == 1) .
43
+ charge cents fails with Declined _ message contains "odd"
44
+ end
45
+ end
46
+
47
+ law `negative amounts are blocked` is
48
+ definition is
49
+ `for all` (cents :: Int32 where cents < 0) . charge cents fails with Blocked
50
+ end
51
+ example `minus one` is
52
+ cents = -1
53
+ expect charge cents fails with Blocked
54
+ expect !(charge cents fails with Declined _)
55
+ end
56
+ end
57
+
58
+ law `even amounts go through` is
59
+ definition is
60
+ `for all` (cents :: Int32 where cents >= 0 && cents <= 100000 && prelude.rem cents 2 == 0) .
61
+ prelude.attempt (charge cents) = Right cents
62
+ end
63
+ end
64
+
65
+ -- Native adapters fail too: their native code raises the runtime's Fail
66
+ -- with a PaymentError, synchronously or from an async adapter.
67
+ refund :: Int32 -> Int32 fails with PaymentError
68
+ async settle :: Int32 -> Int32 fails with PaymentError
69
+
70
+ law `refunds over the limit are too large` is
71
+ definition is
72
+ `for all` (cents :: Int32 where cents > 5000) . refund cents fails with TooLarge 5000
73
+ end
74
+ end
75
+
76
+ law `refunds within the limit go through` is
77
+ definition is
78
+ `for all` (cents :: Int32 where cents >= 0 && cents <= 5000) . prelude.attempt (refund cents) = Right cents
79
+ end
80
+ end
81
+
82
+ law `settling a negative amount is blocked` is
83
+ definition is
84
+ `for all` (cents :: Int32 where cents < 0) . settle cents fails with Blocked
85
+ end
86
+ end
87
+
88
+ law `settling nothing is declined, and says why` is
89
+ definition is settle 0 fails with Declined _ message contains "nothing" end
90
+ end
91
+
92
+ law `settling a positive amount goes through` is
93
+ definition is
94
+ `for all` (cents :: Int32 where cents > 0) . prelude.attempt (settle cents) = Right cents
95
+ end
96
+ end
@@ -0,0 +1,65 @@
1
+ unit example.till
2
+
3
+ -- An ability whose production handler is application code, named in
4
+ -- lawspec.json under handlers. Money is bound to a native type there too, so
5
+ -- the handler's operations take and give that type.
6
+
7
+ type Money is Money cents :: Int64 end
8
+ type PayError is | Declined | Rejected message :: Text end
9
+
10
+ -- A till's drawer. Every handler of it gives back what it takes.
11
+ ability Drawer is
12
+ take :: Money -> Money
13
+ opening :: Money
14
+ laws
15
+ law `a till gives back what it takes` is
16
+ definition is
17
+ `for all` (cents :: Int64 where cents >= 0 && cents <= 1000) . take (Money cents) = Money cents
18
+ end
19
+ end
20
+ end
21
+
22
+ handler fakeDrawer for Drawer is
23
+ take money is money end
24
+ opening is Money 0 end
25
+ end
26
+
27
+ -- A native adapter that fails. Its native code raises the application's own
28
+ -- exceptions; lawspec.json maps them to PayError's constructors.
29
+ pay :: Int64 -> Money uses Drawer fails with PayError
30
+
31
+ law `small payments go through` is
32
+ definition is
33
+ `for all` (cents :: Int64 where cents >= 0 && cents <= 1000) .
34
+ prelude.attempt (pay cents) = Right (Money cents)
35
+ end
36
+ end
37
+
38
+ law `large payments are declined` is
39
+ definition is
40
+ `for all` (cents :: Int64 where cents > 1000 && cents <= 100000) .
41
+ prelude.attempt (pay cents) = Left Declined
42
+ end
43
+ end
44
+
45
+ law `negative payments are rejected` is
46
+ definition is
47
+ `for all` (cents :: Int64 where cents >= -1000 && cents < 0) .
48
+ prelude.attempt (pay cents) = Left (Rejected "negative")
49
+ end
50
+ end
51
+
52
+ -- The same failures, as a law expects them: `fails with` matches the
53
+ -- constructor a mapped exception became, and its message.
54
+ law `large payments fail as declined` is
55
+ definition is
56
+ `for all` (cents :: Int64 where cents > 1000 && cents <= 100000) . pay cents fails with Declined
57
+ end
58
+ end
59
+
60
+ law `negative payments say why they are rejected` is
61
+ definition is
62
+ `for all` (cents :: Int64 where cents >= -1000 && cents < 0) .
63
+ pay cents fails with Rejected _ message contains "negative"
64
+ end
65
+ end
@@ -0,0 +1,75 @@
1
+ unit example.harness
2
+
3
+ -- The laws of a small shop. How they are tested (which inputs, which
4
+ -- handlers, how many cases are enough) is not said here: that is the
5
+ -- harness's business, in harness_testing.lawspec.
6
+
7
+ -- An order: how many items it has, and its total in cents.
8
+ type Order is Order items :: Int32 total :: Int32 end
9
+
10
+ definition itemsOf (order :: Order) :: Int32 is match order with | Order items total -> items end end
11
+ definition totalOf (order :: Order) :: Int32 is match order with | Order items total -> total end end
12
+ definition isEmpty (order :: Order) :: Bool is itemsOf order == 0 end
13
+
14
+ -- The discount an order gets, and a price rounded to tens of cents.
15
+ discount :: Order -> Int32
16
+ roundCents :: Int32 -> Int32
17
+
18
+ law `a discount is never more than the total` is
19
+ definition is
20
+ `for all` (order :: Order where itemsOf order >= 0 && totalOf order >= 0) .
21
+ (discount order <= totalOf order) = true
22
+ end
23
+ end
24
+
25
+ law `rounding is idempotent` is
26
+ definition is
27
+ `for all` (cents :: Int32 where cents >= 0 && cents <= 1000000) .
28
+ roundCents (roundCents cents) = roundCents cents
29
+ end
30
+ end
31
+
32
+ law `rounding never lowers a price` is
33
+ definition is
34
+ `for all` (cents :: Int32 where cents >= 0 && cents <= 1000000) .
35
+ (roundCents cents >= cents) = true
36
+ end
37
+ end
38
+
39
+ -- A ledger records payments. Every law about booking holds for every
40
+ -- lawful ledger; the harness chooses which ones the tests use.
41
+ ability Ledger is
42
+ accept :: Int32 -> Bool
43
+ laws
44
+ law `positive amounts are accepted` is
45
+ definition is `for all` (cents :: Int32 where cents > 0) . accept cents = true end
46
+ end
47
+ end
48
+
49
+ handler fakeLedger for Ledger is
50
+ accept cents is cents > 0 end
51
+ end
52
+
53
+ book :: Int32 -> Bool uses Ledger
54
+
55
+ law `booking a positive amount succeeds` is
56
+ definition is
57
+ `for all` (cents :: Int32 where cents > 0) . book cents = true
58
+ end
59
+ end
60
+
61
+ law `a refund is never booked twice` is
62
+ definition is
63
+ `for all` (cents :: Int32 where cents > 0) . book cents = book cents
64
+ end
65
+ end
66
+
67
+ -- A scratch area the laws may use; it can be emptied between laws, and
68
+ -- laws running at the same time cannot interfere through it.
69
+ type Scratch is Scratch used :: Int32 end
70
+
71
+ resource Scratch is concurrent
72
+ acquire is Scratch 0 end
73
+ release scratch is unitValue end
74
+ reset scratch is unitValue end
75
+ end