├── src
    ├── version.cr
    ├── error.cr
    ├── headers.cr
    ├── jetstream
    │   ├── error.cr
    │   ├── api_error.cr
    │   ├── cluster_info.cr
    │   ├── pub_ack.cr
    │   ├── entity.cr
    │   ├── stream_state.cr
    │   ├── nanoseconds_converter.cr
    │   ├── external_stream.cr
    │   ├── peer_info.cr
    │   ├── error_response.cr
    │   ├── consumer_list_response.cr
    │   ├── stream.cr
    │   ├── errors.cr
    │   ├── stream_source.cr
    │   ├── stream_source_info.cr
    │   ├── nak_backoff.cr
    │   ├── stream_list_response.cr
    │   ├── consumer.cr
    │   ├── stream_get_msg_response.cr
    │   ├── message.cr
    │   ├── pull_subscription.cr
    │   ├── consumers.cr
    │   ├── stream_config.cr
    │   ├── consumer_config.cr
    │   ├── streams.cr
    │   └── client.cr
    ├── jetstream.cr
    ├── headers_converter.cr
    ├── message.cr
    ├── lib_crypto.cr
    ├── nuid.cr
    ├── counter.cr
    ├── nkeys.cr
    ├── objects.cr
    └── services.cr
├── spec
    ├── support
    │   ├── nats_nkeys.seed
    │   └── nats_nkeys.conf
    ├── spec_helper.cr
    ├── nuid_spec.cr
    ├── nkeys_spec.cr
    ├── objects_spec.cr
    ├── counter_spec.cr
    ├── services_spec.cr
    ├── kv_spec.cr
    ├── nats_spec.cr
    └── jetstream_spec.cr
├── .gitignore
├── .travis.yml
├── .editorconfig
├── examples
    ├── pub_sub.cr
    ├── unsub.cr
    ├── bench_sub.cr
    ├── request_reply.cr
    ├── bench_pub.cr
    └── bench_request_reply.cr
├── shard.yml
├── LICENSE
├── README.md
└── docs
    ├── css
        └── style.css
    └── NATS
        └── JetStream
            └── Placement.html


/src/version.cr:
--------------------------------------------------------------------------------
1 | module NATS
2 |   VERSION = "1.5.0"
3 | end
4 | 


--------------------------------------------------------------------------------
/spec/support/nats_nkeys.seed:
--------------------------------------------------------------------------------
1 | SUAJBDIJYQNAQ3WHEG3CRJIZY6JYVOHYXYB63ZLSU44BDPDUO7AOXNMS3Y
2 | 


--------------------------------------------------------------------------------
/src/error.cr:
--------------------------------------------------------------------------------
1 | module NATS
2 |   # Generic error
3 |   class Error < ::Exception
4 |   end
5 | end
6 | 


--------------------------------------------------------------------------------
/src/headers.cr:
--------------------------------------------------------------------------------
1 | require "./message"
2 | 
3 | module NATS
4 |   alias Headers = Message::Headers
5 | end
6 | 


--------------------------------------------------------------------------------
/spec/spec_helper.cr:
--------------------------------------------------------------------------------
1 | require "spec"
2 | 
3 | def be_within(delta, of value)
4 |   be_close value, delta: delta
5 | end
6 | 


--------------------------------------------------------------------------------
/src/jetstream/error.cr:
--------------------------------------------------------------------------------
1 | require "../error"
2 | 
3 | module NATS::JetStream
4 |   class Error < ::NATS::Error
5 |   end
6 | end
7 | 


--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | /lib/
2 | /bin/
3 | /.shards/
4 | *.dwarf
5 | 
6 | # Libraries don't need dependency lock
7 | # Dependencies will be locked in applications that use them
8 | /shard.lock
9 | 


--------------------------------------------------------------------------------
/.travis.yml:
--------------------------------------------------------------------------------
1 | language: crystal
2 | 
3 | # Uncomment the following if you'd like Travis to run specs and check code formatting
4 | # script:
5 | #   - crystal spec
6 | #   - crystal tool format --check
7 | 


--------------------------------------------------------------------------------
/.editorconfig:
--------------------------------------------------------------------------------
 1 | root = true
 2 | 
 3 | [*.cr]
 4 | charset = utf-8
 5 | end_of_line = lf
 6 | insert_final_newline = true
 7 | indent_style = space
 8 | indent_size = 2
 9 | trim_trailing_whitespace = true
10 | 


--------------------------------------------------------------------------------
/spec/support/nats_nkeys.conf:
--------------------------------------------------------------------------------
1 | authorization: {
2 |   users: [
3 |     # seed: SUAJBDIJYQNAQ3WHEG3CRJIZY6JYVOHYXYB63ZLSU44BDPDUO7AOXNMS3Y
4 |     { nkey: UA33M7GXKKN3NBIB72E6QEHDCVF3F35VL4EGEQVUHJWK427ZQ22UWKUB }
5 |   ]
6 | }
7 | 


--------------------------------------------------------------------------------
/src/jetstream/api_error.cr:
--------------------------------------------------------------------------------
 1 | require "./entity"
 2 | 
 3 | module NATS::JetStream
 4 |   struct APIError < Entity
 5 |     getter code : Int64
 6 |     getter err_code : UInt16?
 7 |     getter description : String?
 8 |   end
 9 | 
10 |   deprecate_api_v1 APIError
11 | end
12 | 


--------------------------------------------------------------------------------
/examples/pub_sub.cr:
--------------------------------------------------------------------------------
 1 | require "../src/nats"
 2 | 
 3 | nats = NATS::Client.new
 4 | # Ensure we close the client explicitly to flush any buffered messages
 5 | at_exit { nats.close }
 6 | 
 7 | nats.subscribe "foo" do |msg|
 8 |   pp msg
 9 | end
10 | 
11 | nats.publish "foo", "bar"
12 | 


--------------------------------------------------------------------------------
/shard.yml:
--------------------------------------------------------------------------------
 1 | name: nats
 2 | version: 1.5.0
 3 | 
 4 | authors:
 5 |   - Jamie Gaskins <jgaskins@hey.com>
 6 | 
 7 | dependencies:
 8 |   base32: { github: jgaskins/base32 }
 9 |   openssl_ext:
10 |     github: spider-gazelle/openssl_ext
11 |     version: ~> 2.6
12 | 
13 | crystal: ">= 0.35.1, < 2.0.0"
14 | 
15 | license: MIT
16 | 


--------------------------------------------------------------------------------
/examples/unsub.cr:
--------------------------------------------------------------------------------
 1 | require "../src/nats"
 2 | 
 3 | nats = NATS::Client.new
 4 | 
 5 | subscription = nats.subscribe "foo" do |msg|
 6 |   puts String.new msg.body
 7 | end
 8 | 
 9 | nats.unsubscribe subscription.sid, max_messages: 3
10 | 
11 | 500.times do |i|
12 |   nats.publish "foo", i.to_s
13 | end
14 | 
15 | sleep 1.second
16 | 


--------------------------------------------------------------------------------
/src/jetstream/cluster_info.cr:
--------------------------------------------------------------------------------
 1 | require "./entity"
 2 | require "./peer_info"
 3 | 
 4 | module NATS::JetStream
 5 |   struct ClusterInfo < Entity
 6 |     getter name : String?
 7 |     getter leader : String?
 8 |     getter replicas : Array(PeerInfo) { [] of PeerInfo }
 9 |   end
10 | 
11 |   deprecate_api_v1 ClusterInfo
12 | end
13 | 


--------------------------------------------------------------------------------
/src/jetstream/pub_ack.cr:
--------------------------------------------------------------------------------
 1 | require "json"
 2 | require "./entity"
 3 | 
 4 | module NATS::JetStream
 5 |   struct PubAck < Entity
 6 |     getter stream : String
 7 |     @[JSON::Field(key: "seq")]
 8 |     getter sequence : Int64
 9 |     getter? duplicate : Bool = false
10 |     getter domain : String?
11 |     getter val : String?
12 |   end
13 | 
14 |   deprecate_api_v1 PubAck
15 | end
16 | 


--------------------------------------------------------------------------------
/src/jetstream/entity.cr:
--------------------------------------------------------------------------------
 1 | module NATS::JetStream
 2 |   abstract struct Entity
 3 |     include JSON::Serializable
 4 |   end
 5 | 
 6 |   macro deprecate_api_v1(name)
 7 |     module ::NATS::JetStream::API::V1
 8 |       @[Deprecated("The API::V1 namespace was unnecessary, use NATS::JetStream::{{name}} instead")]
 9 |       alias {{name}} = JetStream::{{name}}
10 |     end
11 |   end
12 | end
13 | 


--------------------------------------------------------------------------------
/src/jetstream/stream_state.cr:
--------------------------------------------------------------------------------
 1 | require "./entity"
 2 | 
 3 | module NATS::JetStream
 4 |   struct StreamState < Entity
 5 |     getter messages : Int64
 6 |     getter bytes : Int64
 7 |     getter first_seq : Int64
 8 |     getter first_ts : Time
 9 |     getter last_seq : Int64
10 |     getter last_ts : Time
11 |     getter consumer_count : Int32
12 |   end
13 | 
14 |   deprecate_api_v1 StreamState
15 | end
16 | 


--------------------------------------------------------------------------------
/examples/bench_sub.cr:
--------------------------------------------------------------------------------
 1 | require "../src/nats"
 2 | 
 3 | nats = NATS::Client.new
 4 | 
 5 | count = 0
 6 | start = Time.monotonic
 7 | nats.subscribe "foo", queue_group: "bar" do |msg|
 8 |   count += 1
 9 | 
10 |   if count >= 500_000
11 |     pp incoming_msgs_per_sec: (count // (Time.monotonic - start).total_seconds).format
12 |     Fiber.yield
13 |     count = 0
14 |     start = Time.monotonic
15 |   end
16 | end
17 | 
18 | sleep
19 | 


--------------------------------------------------------------------------------
/src/jetstream/nanoseconds_converter.cr:
--------------------------------------------------------------------------------
 1 | require "json"
 2 | 
 3 | module NATS::JetStream
 4 |   module NanosecondsConverter
 5 |     def self.to_json(span : Time::Span, json : JSON::Builder)
 6 |       json.number span.total_nanoseconds.to_i64
 7 |     end
 8 | 
 9 |     def self.from_json(json : JSON::PullParser)
10 |       json.read_int.nanoseconds
11 |     end
12 |   end
13 | 
14 |   deprecate_api_v1 NanosecondsConverter
15 | end
16 | 


--------------------------------------------------------------------------------
/src/jetstream/external_stream.cr:
--------------------------------------------------------------------------------
 1 | require "json"
 2 | require "./entity"
 3 | 
 4 | module NATS::JetStream
 5 |   struct ExternalStream < Entity
 6 |     @[JSON::Field(key: "api")]
 7 |     getter api_prefix : String
 8 |     @[JSON::Field(key: "deliver")]
 9 |     getter deliver_prefix : String
10 | 
11 |     def initialize(*, @api_prefix = "", @deliver_prefix = "")
12 |     end
13 |   end
14 | 
15 |   deprecate_api_v1 ExternalStream
16 | end
17 | 


--------------------------------------------------------------------------------
/src/jetstream/peer_info.cr:
--------------------------------------------------------------------------------
 1 | require "./entity"
 2 | require "./nanoseconds_converter"
 3 | 
 4 | module NATS::JetStream
 5 |   struct PeerInfo < Entity
 6 |     getter name : String
 7 |     getter? current : Bool
 8 |     getter? offline : Bool = false
 9 |     @[JSON::Field(converter: ::NATS::JetStream::NanosecondsConverter)]
10 |     getter active : Time::Span
11 |     getter lag : UInt64?
12 |   end
13 | 
14 |   deprecate_api_v1 PeerInfo
15 | end
16 | 


--------------------------------------------------------------------------------
/src/jetstream/error_response.cr:
--------------------------------------------------------------------------------
 1 | require "json"
 2 | require "./errors"
 3 | 
 4 | module NATS::JetStream
 5 |   struct ErrorResponse
 6 |     include JSON::Serializable
 7 | 
 8 |     getter error : Error
 9 | 
10 |     struct Error
11 |       include JSON::Serializable
12 | 
13 |       getter code : Int32
14 |       getter err_code : Errors = :none
15 |       getter description : String
16 |     end
17 |   end
18 | 
19 |   deprecate_api_v1 ErrorResponse
20 | end
21 | 


--------------------------------------------------------------------------------
/examples/request_reply.cr:
--------------------------------------------------------------------------------
 1 | require "../src/nats"
 2 | 
 3 | nats = NATS::Client.new
 4 | 
 5 | subscription = nats.subscribe "foo" do |msg|
 6 |   if msg.reply_to
 7 |     nats.reply msg, String.new(msg.body).upcase.to_slice
 8 |   end
 9 | end
10 | 
11 | puts "Sending request..."
12 | started_at = Time.monotonic
13 | if response = nats.request("foo", "bar", timeout: 2.seconds)
14 |   puts "Received #{String.new(response.body)} in #{Time.monotonic - started_at}"
15 | end
16 | 


--------------------------------------------------------------------------------
/src/jetstream/consumer_list_response.cr:
--------------------------------------------------------------------------------
 1 | require "./entity"
 2 | require "./consumer"
 3 | 
 4 | module NATS::JetStream
 5 |   struct ConsumerListResponse < Entity
 6 |     include Enumerable(Consumer)
 7 | 
 8 |     getter total : Int64
 9 |     getter offset : Int64
10 |     getter limit : Int64
11 |     getter consumers : Array(Consumer)
12 | 
13 |     def each(&)
14 |       consumers.each { |c| yield c }
15 |     end
16 |   end
17 | 
18 |   deprecate_api_v1 ConsumerListResponse
19 | end
20 | 


--------------------------------------------------------------------------------
/src/jetstream/stream.cr:
--------------------------------------------------------------------------------
 1 | require "./entity"
 2 | require "./stream_config"
 3 | require "./stream_state"
 4 | require "./cluster_info"
 5 | require "./stream_source_info"
 6 | 
 7 | module NATS::JetStream
 8 |   struct Stream < Entity
 9 |     getter config : StreamConfig
10 |     getter created : Time
11 |     getter state : StreamState
12 |     getter cluster : ClusterInfo?
13 |     getter mirror : StreamSourceInfo?
14 |     getter sources : Array(StreamSourceInfo) { [] of StreamSourceInfo }
15 |   end
16 | 
17 |   deprecate_api_v1 Stream
18 | end
19 | 


--------------------------------------------------------------------------------
/src/jetstream/errors.cr:
--------------------------------------------------------------------------------
 1 | require "json"
 2 | 
 3 | module NATS::JetStream
 4 |   enum Errors : Int32
 5 |     # https://github.com/nats-io/nats-server/blob/main/server/errors.json
 6 | 
 7 |     None                              =     0
 8 |     ConsumerNotFound                  = 10014
 9 |     NoMessageFound                    = 10037
10 |     StreamNotFound                    = 10059
11 |     StreamWrongLastSequence           = 10071
12 |     MaximumMessagesPerSubjectExceeded = 10077
13 | 
14 |     def self.new(json : JSON::PullParser)
15 |       new json.read_int.to_i
16 |     end
17 |   end
18 | end
19 | 


--------------------------------------------------------------------------------
/src/jetstream/stream_source.cr:
--------------------------------------------------------------------------------
 1 | require "./entity"
 2 | require "./external_stream"
 3 | 
 4 | module NATS::JetStream
 5 |   struct StreamSource < Entity
 6 |     getter name : String
 7 |     getter opt_start_seq : UInt64?
 8 |     getter opt_start_time : Time?
 9 |     getter filter_subject : String?
10 |     getter external : ExternalStream?
11 | 
12 |     def initialize(
13 |       @name,
14 |       @opt_start_seq = nil,
15 |       @opt_start_time = nil,
16 |       @filter_subject = nil,
17 |       @external = nil,
18 |     )
19 |     end
20 |   end
21 | 
22 |   deprecate_api_v1 StreamSource
23 | end
24 | 


--------------------------------------------------------------------------------
/src/jetstream.cr:
--------------------------------------------------------------------------------
 1 | require "json"
 2 | require "./nats"
 3 | require "./error"
 4 | require "./jetstream/client"
 5 | 
 6 | module NATS
 7 |   # NATS JetStream provides at-least-once delivery guarantees with the
 8 |   # possibility of exactly-once for some use cases, allowing NATS to be used for
 9 |   # scenarios where 100% delivery of messages and events is required.
10 |   module JetStream
11 |   end
12 | 
13 |   class Client
14 |     # Returns a `NATS::JetStream::Client` that uses this client's connection to
15 |     # the NATS server.
16 |     def jetstream
17 |       @jetstream ||= JetStream::Client.new(self)
18 |     end
19 |   end
20 | end
21 | 


--------------------------------------------------------------------------------
/src/headers_converter.cr:
--------------------------------------------------------------------------------
 1 | require "json/pull_parser"
 2 | 
 3 | require "./headers"
 4 | 
 5 | module NATS::HeadersConverter
 6 |   extend self
 7 | 
 8 |   def from_json(json : JSON::PullParser) : Headers
 9 |     Headers.new.merge! Hash(String, String | Array(String)).new(json)
10 |   end
11 | 
12 |   def to_json(headers : Headers, json : JSON::Builder) : Nil
13 |     json.object do
14 |       headers.each do |key, values|
15 |         json.field key do
16 |           json.array do
17 |             values.each do |value|
18 |               json.scalar value
19 |             end
20 |           end
21 |         end
22 |       end
23 |     end
24 |   end
25 | end
26 | 


--------------------------------------------------------------------------------
/spec/nuid_spec.cr:
--------------------------------------------------------------------------------
 1 | require "./spec_helper"
 2 | require "../src/nuid"
 3 | 
 4 | module NATS
 5 |   describe NUID do
 6 |     # Adapted from https://github.com/nats-io/nuid/blob/94bac9a67a7388c50abc3f3d127cb9af09ec110b/nuid_test.go#L27-L37
 7 |     it "is always initialized" { NUID.global.should_not be_nil }
 8 |     it "always has a prefix" { NUID.global.prefix.should_not be_nil }
 9 |     it "has a nonzero prefix" { NUID.global.sequence.should_not eq 0 }
10 | 
11 |     it "can get the next NUID, which changes the global NUID" do
12 |       nuid = NUID.global.to_s
13 |       NUID.next.should be_a String
14 |       NUID.global.should_not eq nuid
15 |     end
16 |   end
17 | end
18 | 


--------------------------------------------------------------------------------
/examples/bench_pub.cr:
--------------------------------------------------------------------------------
 1 | require "../src/nats"
 2 | 
 3 | nats = Array.new(3) { NATS::Client.new }
 4 | 
 5 | # nats.subscribe "foo" do |msg|
 6 | #   pp msg
 7 | # end
 8 | 
 9 | # nats.publish "foo", "bar"
10 | 
11 | # sleep 1.second
12 | # exit 0
13 | 
14 | count = 0i64
15 | total = 0i64
16 | start = Time.monotonic
17 | loop do
18 |   nats.sample.publish "foo", "bar"
19 |   total += 1i64
20 |   count += 1i64
21 | 
22 |   if count >= 10_000_000i64
23 |     pp outgoing_msg_per_sec: (count // (Time.monotonic - start).total_seconds).format
24 |     Fiber.yield
25 |     count = 0i64
26 |     start = Time.monotonic
27 |   end
28 | rescue ex
29 |   pp ex
30 |   pp total: total
31 |   break
32 | end
33 | 


--------------------------------------------------------------------------------
/src/jetstream/stream_source_info.cr:
--------------------------------------------------------------------------------
 1 | require "./entity"
 2 | require "./external_stream"
 3 | require "./nanoseconds_converter"
 4 | require "./api_error"
 5 | 
 6 | module NATS::JetStream
 7 |   struct StreamSourceInfo < Entity
 8 |     getter name : String
 9 |     getter external : ExternalStream?
10 |     @[JSON::Field(converter: ::NATS::JetStream::NanosecondsConverter)]
11 |     getter lag : Time::Span
12 |     @[JSON::Field(converter: ::NATS::JetStream::NanosecondsConverter)]
13 |     getter active : Time::Span
14 |     getter error : APIError?
15 | 
16 |     def initialize(@name, @external = nil, @lag = 0.seconds, @active = 0.seconds, @error = nil)
17 |     end
18 |   end
19 | 
20 |   deprecate_api_v1 StreamSourceInfo
21 | end
22 | 


--------------------------------------------------------------------------------
/src/message.cr:
--------------------------------------------------------------------------------
 1 | require "http/headers"
 2 | 
 3 | module NATS
 4 |   struct Message
 5 |     getter subject : String
 6 |     getter reply_to : String?
 7 |     getter headers : Headers { Headers.new }
 8 |     getter data_string : String
 9 | 
10 |     alias Headers = HTTP::Headers
11 | 
12 |     def initialize(@subject, data @data_string, @reply_to = nil, @headers = nil)
13 |     end
14 | 
15 |     def data
16 |       data_string.to_slice
17 |     end
18 | 
19 |     @[Deprecated("Instantiating a new IO::Memory for each message made them heavier than intended, so we're now recommending using `String.new(msg.body)`")]
20 |     def body_io
21 |       @body_io ||= IO::Memory.new(@body)
22 |     end
23 | 
24 |     def body
25 |       data
26 |     end
27 |   end
28 | end
29 | 


--------------------------------------------------------------------------------
/examples/bench_request_reply.cr:
--------------------------------------------------------------------------------
 1 | require "../src/nats"
 2 | 
 3 | nats = NATS::Client.new
 4 | 
 5 | subscription = nats.subscribe "foo" do |msg|
 6 |   if msg.reply_to
 7 |     nats.reply msg, msg.body
 8 |   end
 9 | end
10 | 
11 | count = 0i64
12 | total = 0i64
13 | start = Time.monotonic
14 | 200.times do
15 |   spawn do
16 |     loop do
17 |       nats.request "foo", "bar", timeout: 2.seconds
18 |       total += 1i64
19 |       count += 1i64
20 | 
21 |       if count >= 100_000
22 |         pp outgoing_msg_per_sec: (count // (Time.monotonic - start).total_seconds).format
23 |         count = 0i64
24 |         start = Time.monotonic
25 |         Fiber.yield
26 |       end
27 |     rescue ex
28 |       pp ex
29 |       pp total: total
30 |       break
31 |     end
32 |   end
33 | end
34 | 
35 | sleep
36 | 


--------------------------------------------------------------------------------
/src/jetstream/nak_backoff.cr:
--------------------------------------------------------------------------------
 1 | module NATS::JetStream
 2 |   # Common `nack` backoff strategies give a simple shorthand for setting the
 3 |   # delays on subsequent delivery attempts.
 4 |   #
 5 |   # ```
 6 |   # nats = NATS::Client.new
 7 |   #
 8 |   # jetstream.subscribe consumer do |msg|
 9 |   #   # do some work
10 |   #   jetstream.ack msg
11 |   # rescue ex
12 |   #   jetstream.nack msg, backoff: :exponential
13 |   #   raise ex
14 |   # end
15 |   # ```
16 |   enum NAKBackoff
17 |     # Exponential backoff starts at a delay of 1/16th of a second and
18 |     # doubles every time the message is nacked with this strategy. This has
19 |     # the effect of running the first 3 attempts roughly immediately so that
20 |     # an uncommon but not unexpected failure (API call in a downstream
21 |     # service returns a 500) doesn't need to wait several seconds unless it
22 |     # truly needs to.
23 |     Exponential
24 | 
25 |     # Linear backoff delays for 1 second for each time the message is nacked
26 |     # with this strategy.
27 |     Linear
28 |   end
29 | end
30 | 


--------------------------------------------------------------------------------
/spec/nkeys_spec.cr:
--------------------------------------------------------------------------------
 1 | require "./spec_helper"
 2 | 
 3 | require "../src/nkeys"
 4 | 
 5 | module NATS
 6 |   describe NKeys do
 7 |     # Values taken from the Ruby NKEYS library specs:
 8 |     # https://github.com/nats-io/nkeys.rb/blob/a942c0f607c410860845803d893b1e53673e8aa3/spec/nkeys_spec.rb#L19-L26
 9 |     seed = "SUAMLK2ZNL35WSMW37E7UD4VZ7ELPKW7DHC3BWBSD2GCZ7IUQQXZIORRBU"
10 |     nkeys = NKeys.new(seed)
11 | 
12 |     it "creates a public key" do
13 |       # https://github.com/nats-io/nkeys.rb/blob/a942c0f607c410860845803d893b1e53673e8aa3/spec/nkeys_spec.rb#L94-L95
14 |       Base32.encode(nkeys.keypair.public_key, pad: false).should eq "UCK5N7N66OBOINFXAYC2ACJQYFSOD4VYNU6APEJTAVFZB2SVHLKGEW7L"
15 |     end
16 | 
17 |     it "signs a nonce" do
18 |       nonce = "PXoWU7zWAMt75FY"
19 | 
20 |       signed_nonce = nkeys.keypair.sign(nonce)
21 |       encoded_signed_nonce = Base64.strict_encode(signed_nonce)
22 | 
23 |       encoded_signed_nonce.should eq("ZaAiVDgB5CeYoXoQ7cBCmq+ZllzUnGUoDVb8C7PilWvCs8XKfUchAUhz2P4BYAF++Dg3w05CqyQFRDiGL6LrDw==")
24 |     end
25 |   end
26 | end
27 | 


--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
 1 | The MIT License (MIT)
 2 | 
 3 | Copyright (c) 2020 your-name-here
 4 | 
 5 | Permission is hereby granted, free of charge, to any person obtaining a copy
 6 | of this software and associated documentation files (the "Software"), to deal
 7 | in the Software without restriction, including without limitation the rights
 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 | 
12 | The above copyright notice and this permission notice shall be included in
13 | all copies or substantial portions of the Software.
14 | 
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
21 | THE SOFTWARE.
22 | 


--------------------------------------------------------------------------------
/src/lib_crypto.cr:
--------------------------------------------------------------------------------
 1 | require "openssl_ext/lib_crypto"
 2 | 
 3 | lib LibCrypto
 4 |   enum PKEY : LibC::Int
 5 |     # https://github.com/openssl/openssl/blob/f2f7cff20377f7402b132a19d953a9d998be26aa/include/openssl/evp.h#L62
 6 |     # https://github.com/openssl/openssl/blob/f2f7cff20377f7402b132a19d953a9d998be26aa/include/openssl/obj_mac.h#L4996
 7 |     ED25519 = 1087
 8 |   end
 9 | 
10 |   fun evp_pkey_new_raw_private_key = EVP_PKEY_new_raw_private_key(
11 |     type : PKEY,
12 |     engine : Engine*,
13 |     key : LibC::Char*,
14 |     keylen : LibC::SizeT,
15 |   ) : EvpPKey*
16 | 
17 |   fun evp_pkey_get_raw_public_key = EVP_PKEY_get_raw_public_key(
18 |     key : EvpPKey*,
19 |     pub : LibC::Char*,
20 |     len : LibC::SizeT*,
21 |   ) : LibC::Int
22 | 
23 |   fun evp_digest_sign_init = EVP_DigestSignInit(
24 |     context : EVP_MD_CTX,
25 |     pkey_context : EVP_PKEY_CTX**,
26 |     type : Void*,
27 |     engine : Void*,
28 |     pkey : EvpPKey*,
29 |   ) : LibC::Int
30 | 
31 |   fun evp_digest_sign = EVP_DigestSign(
32 |     context : EVP_MD_CTX,
33 |     sigret : LibC::Char*,
34 |     siglen : LibC::SizeT*,
35 |     tbs : LibC::Char*,
36 |     tbslen : LibC::SizeT,
37 |   ) : LibC::Int
38 | 
39 |   fun err_error_string_n = ERR_error_string_n(e : ULong, buf : Char*, len : SizeT)
40 | end
41 | 


--------------------------------------------------------------------------------
/src/jetstream/stream_list_response.cr:
--------------------------------------------------------------------------------
 1 | require "json"
 2 | 
 3 | require "./entity"
 4 | require "./stream"
 5 | require "./client"
 6 | 
 7 | module NATS::JetStream
 8 |   struct StreamListResponse < Entity
 9 |     include Enumerable(Stream)
10 | 
11 |     getter total : Int64
12 |     getter offset : Int64
13 |     getter limit : Int64
14 |     getter streams : Array(Stream) { [] of Stream }
15 |     @[JSON::Field(ignore: true)]
16 |     protected property! js : JetStream::Client
17 |     @[JSON::Field(ignore: true)]
18 |     protected property subject : String?
19 | 
20 |     def self.new(js : JetStream::Client, json : JSON::PullParser, subject : String? = nil)
21 |       response = new json
22 |       response.js = js
23 |       response.subject = subject
24 |       response
25 |     end
26 | 
27 |     def each(&block : Stream ->) : Nil
28 |       streams.each { |s| yield s }
29 |       new_offset = offset + limit
30 |       total = self.total
31 |       while total > new_offset
32 |         response = js
33 |           .stream
34 |           .list(subject: subject, offset: new_offset, limit: limit)
35 | 
36 |         response
37 |           .streams
38 |           .each { |s| yield s }
39 |         total = response.total
40 |         new_offset = response.offset + response.limit
41 |       end
42 |     end
43 |   end
44 | 
45 |   deprecate_api_v1 StreamListResponse
46 | end
47 | 


--------------------------------------------------------------------------------
/src/jetstream/consumer.cr:
--------------------------------------------------------------------------------
 1 | require "./entity"
 2 | require "./consumer_config"
 3 | require "./cluster_info"
 4 | 
 5 | module NATS::JetStream
 6 |   struct Consumer < Entity
 7 |     # The name of the stream this consumer sources its messages from
 8 |     getter stream_name : String
 9 | 
10 |     # The name of this consumer
11 |     getter name : String
12 | 
13 |     # The timestamp when this consumer was created
14 |     getter created : Time
15 | 
16 |     # The configuration used to create this consumer (including its defaults)
17 |     getter config : ConsumerConfig
18 | 
19 |     # The number of times this consumer has delivered messages for this stream
20 |     getter delivered : Sequence
21 | 
22 |     # The number of messages that have been acknowledged for this consumer/stream
23 |     getter ack_floor : Sequence
24 | 
25 |     # The number of messages currently in-flight that are awaiting acknowledgement
26 |     getter num_ack_pending : Int64
27 | 
28 |     # The number of messages that have been redelivered
29 |     getter num_redelivered : Int64
30 | 
31 |     # The number of messages that are currently waiting
32 |     getter num_waiting : Int64
33 | 
34 |     # The number of messages in the stream that this consumer has not delivered at all yet
35 |     getter num_pending : Int64
36 | 
37 |     # Where this consumer's data lives in the cluster
38 |     getter cluster : ClusterInfo?
39 | 
40 |     getter? push_bound : Bool = false
41 | 
42 |     # The sequence represense a cursor for how many messages have been
43 |     # delivered or acknowledged for this consumer and stream.
44 |     struct Sequence < Entity
45 |       getter consumer_seq : Int64
46 |       getter stream_seq : Int64
47 |     end
48 |   end
49 | 
50 |   deprecate_api_v1 Consumer
51 | end
52 | 


--------------------------------------------------------------------------------
/src/nuid.cr:
--------------------------------------------------------------------------------
 1 | module NATS
 2 |   class NUID
 3 |     DIGITS          = "#{("0".."9").join}#{("A".."Z").join}#{("a".."z").join}".to_slice
 4 |     BASE            =                     62
 5 |     PREFIX_LENGTH   =                     12
 6 |     SEQUENCE_LENGTH =                     10
 7 |     MAX_SEQUENCE    = 839299365868340224_i64
 8 |     MIN_INCREMENT   =                 33_i64
 9 |     MAX_INCREMENT   =                333_i64
10 |     TOTAL_LENGTH    = PREFIX_LENGTH + SEQUENCE_LENGTH
11 | 
12 |     class_getter global : self { new }
13 | 
14 |     getter prefix : Bytes { Bytes.new(PREFIX_LENGTH) }
15 |     getter sequence : Atomic(Int64)
16 |     getter increment : Int64
17 | 
18 |     def initialize(random = Random.new)
19 |       @sequence = Atomic.new(random.rand(MAX_SEQUENCE).abs)
20 |       @increment = random.rand(MIN_INCREMENT..MAX_INCREMENT)
21 |       randomize_prefix
22 |     end
23 | 
24 |     def self.next
25 |       global.next
26 |     end
27 | 
28 |     def next
29 |       seq = sequence.add increment
30 |       if seq >= MAX_SEQUENCE - increment
31 |         initialize
32 |       end
33 | 
34 |       stringify seq
35 |     end
36 | 
37 |     def to_s
38 |       stringify sequence.get
39 |     end
40 | 
41 |     private def stringify(seq : Int64)
42 |       String.new 22 do |buffer|
43 |         prefix.copy_to buffer, prefix.bytesize
44 | 
45 |         SEQUENCE_LENGTH.times do |i|
46 |           buffer[21 - i] = DIGITS[seq % BASE]
47 |           seq //= BASE
48 |         end
49 | 
50 |         {22, 22}
51 |       end
52 |     end
53 | 
54 |     private def randomize_prefix
55 |       bytes = Random::Secure.random_bytes(PREFIX_LENGTH)
56 |       bytes.each_with_index do |byte, index|
57 |         prefix[index] = DIGITS[byte % BASE]
58 |       end
59 |     end
60 |   end
61 | end
62 | 


--------------------------------------------------------------------------------
/spec/objects_spec.cr:
--------------------------------------------------------------------------------
 1 | require "./spec_helper"
 2 | require "../src/objects"
 3 | require "uuid"
 4 | 
 5 | private macro test(name)
 6 |   it {{name}} do
 7 |     name = UUID.random.to_s
 8 |     bucket = obj.create_bucket(name)
 9 |     begin
10 |       {{yield}}
11 |     ensure
12 |       obj.delete_bucket name
13 |     end
14 |   end
15 | end
16 | 
17 | module NATS
18 |   nats = Client.new
19 |   obj = nats.objects
20 | 
21 |   describe Objects do
22 |     it "creates and deletes object stores" do
23 |       name = UUID.random.to_s
24 | 
25 |       bucket = obj.create_bucket(name, storage: :memory)
26 | 
27 |       bucket.should be_a Objects::Bucket
28 |     ensure
29 |       if name && bucket
30 |         obj.delete_bucket(name)
31 |       end
32 |     end
33 | 
34 |     test "creates an object from a string" do
35 |       bucket.put "key", "value", headers: NATS::Headers{"foo" => "bar"}
36 | 
37 |       info = bucket.get_info!("key")
38 | 
39 |       info.digest.should eq "SHA-256=#{sha256("value")}"
40 |       info.headers["foo"].should eq "bar"
41 |       info.size.should eq 5
42 |       info.chunks.should eq 1 # We used the default chunk size of 128KB, which easily holds 5 bytes
43 |       bucket.get!("key").read_string(info.size).should eq "value"
44 |     end
45 | 
46 |     test "creates an object from a file" do
47 |       file = File.tempfile { |f| f << "value" }
48 | 
49 |       File.open(file.path) { |f| bucket.put "key", f }
50 | 
51 |       info = bucket.get_info!("key")
52 |       expected_digest = "SHA-256=#{sha256("value")}"
53 |       info.digest.should eq expected_digest
54 |       bucket.get!("key").read_string(info.size).should eq "value"
55 |     ensure
56 |       file.delete if file
57 |     end
58 | 
59 |     test "deals with objects large enough to invoke flow control" do
60 |       io = IO::Memory.new("*" * 10_000_000)
61 | 
62 |       bucket.put "key", io
63 |       info = bucket.get_info!("key")
64 |       data = bucket.get!("key").gets_to_end
65 | 
66 |       data.should eq io.to_s
67 |     end
68 | 
69 |     test "gets keys for a bucket" do
70 |       bucket.put "key", "value", headers: Headers{"foo" => "bar"}
71 | 
72 |       obj.keys(bucket.name).should contain "key"
73 |     end
74 | 
75 |     test "gets info for a key that has dots in it" do
76 |       bucket.put "key.value", "value"
77 | 
78 |       obj.get_info(bucket.name, "key.value").should_not be_nil
79 |     end
80 |   end
81 | end
82 | 
83 | private def sha256(string : String)
84 |   Base64.urlsafe_encode(Digest::SHA256.new.tap { |sha| sha << string }.final)
85 | end
86 | 


--------------------------------------------------------------------------------
/src/jetstream/stream_get_msg_response.cr:
--------------------------------------------------------------------------------
 1 | require "json"
 2 | 
 3 | require "./entity"
 4 | 
 5 | module NATS::JetStream
 6 |   struct StreamGetMsgResponse < Entity
 7 |     getter message : Message
 8 | 
 9 |     def initialize(*, @message)
10 |     end
11 | 
12 |     struct Message < Entity
13 |       include JSON::Serializable
14 | 
15 |       getter subject : String
16 |       getter seq : Int64
17 |       @[JSON::Field(key: "data", converter: ::NATS::JetStream::StreamGetMsgResponse::Message::Base64Data)]
18 |       getter data_string : String
19 |       @[JSON::Field(key: "hdrs", converter: ::NATS::JetStream::StreamGetMsgResponse::Message::HeadersConverter)]
20 |       getter headers : Headers { Headers.new }
21 |       getter time : Time
22 | 
23 |       def initialize(
24 |         *,
25 |         @subject,
26 |         @seq,
27 |         @data_string,
28 |         @headers,
29 |         @time,
30 |       )
31 |       end
32 | 
33 |       def data : Bytes
34 |         data_string.to_slice
35 |       end
36 | 
37 |       module Base64Data
38 |         def self.from_json(json : JSON::PullParser)
39 |           ::Base64.decode_string json.read_string
40 |         end
41 | 
42 |         def self.to_json(value : Bytes, json : JSON::Builder)
43 |           json.string ::Base64.encode(value)
44 |         end
45 |       end
46 | 
47 |       module HeadersConverter
48 |         def self.from_json(json : JSON::PullParser)
49 |           if string = json.read_string_or_null
50 |             # Decoded string will be in the format:
51 |             #   "NATS/1.0\r\nHeader1: Value1\r\nHeader2: Value2\r\n\r\n"
52 |             # So we want to omit the first line (preamble) and the last
53 |             # line (it's blank).
54 |             raw = Base64.decode_string(string)
55 |             header_count = raw.count('\n') - 2
56 |             headers = Headers.new
57 | 
58 |             raw.each_line do |line|
59 |               if separator_index = line.index(':')
60 |                 key = line[0...separator_index]
61 |                 value = line[separator_index + 2..]
62 |                 headers[key] = value
63 |               end
64 |             end
65 | 
66 |             headers
67 |           end
68 |         end
69 | 
70 |         def self.to_json(headers : NATS::Headers, json : JSON::Builder)
71 |           json.object do
72 |             headers.each do |(key, value)|
73 |               json.field key, value
74 |             end
75 |           end
76 |         end
77 |       end
78 |     end
79 |   end
80 | 
81 |   deprecate_api_v1 StreamGetMsgResponse
82 | end
83 | 


--------------------------------------------------------------------------------
/spec/counter_spec.cr:
--------------------------------------------------------------------------------
 1 | require "./spec_helper"
 2 | require "../src/counter"
 3 | 
 4 | private macro create_counter(name, subjects, **counter_options)
 5 |   nats.counter.create(
 6 |     name: {{name}},
 7 |     subjects: {{subjects}},
 8 |     storage: :memory,
 9 |     {{counter_options.double_splat}}
10 |   )
11 | end
12 | 
13 | private macro test(name, counter_options = {} of String => String, **options)
14 |   it({{name}}, {{options.double_splat}}) do
15 |     write_subject = UUID.random.to_s
16 |     stream_name = UUID.random.to_s
17 |     counter = create_counter(stream_name, [write_subject], {{counter_options.double_splat}})
18 | 
19 |     begin
20 |       {{yield}}
21 |     ensure
22 |       nats.jetstream.stream.delete stream_name
23 |     end
24 |   end
25 | end
26 | 
27 | nats = NATS::Client.new
28 |   .on_error { |ex| Log.for(NATS).error(exception: ex) }
29 | 
30 | describe NATS::Counter do
31 |   test "increments a counter" do
32 |     nats.counter.increment(write_subject).should eq 1
33 |     nats.counter.increment(write_subject).should eq 2
34 |   end
35 | 
36 |   test "gets the value of a counter" do
37 |     nats.counter.get(write_subject).should eq 0
38 | 
39 |     nats.counter.increment write_subject
40 |     nats.counter.get(write_subject).should eq 1
41 | 
42 |     nats.counter.increment write_subject, by: 99
43 |     nats.counter.get(write_subject).should eq 100
44 |   end
45 | 
46 |   test "increments a counter by a value other than 1" do
47 |     delta = rand(2i64..Int64::MAX)
48 | 
49 |     nats.counter.increment(write_subject, by: delta).should eq delta
50 |   end
51 | 
52 |   test "decrements a counter" do
53 |     nats.counter.increment write_subject, by: 1000
54 |     nats.counter.decrement(write_subject).should eq 999
55 |     nats.counter.decrement(write_subject, by: 900).should eq 99
56 |   end
57 | 
58 |   test "resets a counter" do
59 |     nats.counter.increment write_subject, by: 100
60 | 
61 |     nats.counter.reset write_subject
62 | 
63 |     nats.counter.get(write_subject).should eq 0
64 |   end
65 | 
66 |   test "sets a counter to a specific value" do
67 |     nats.counter.set write_subject, 1234
68 | 
69 |     nats.counter.get(write_subject).should eq 1234
70 |   end
71 | 
72 |   test "can increment without waiting for the server to acknowledge" do
73 |     1_000.times do
74 |       nats.counter.increment! write_subject
75 |     end
76 |     # Do something that *does* wait for the server to ack before we can assert
77 |     # on the value. Otherwise, we get inconsistent results.
78 |     nats.counter.increment write_subject
79 | 
80 |     nats.counter.get(write_subject).should eq 1_001
81 |   end
82 | 
83 |   test "can decrement without waiting for the server to acknowledge" do
84 |     1_000.times do
85 |       nats.counter.decrement! write_subject
86 |     end
87 |     # Do something that *does* wait for the server to ack before we can assert
88 |     # on the value. Otherwise, we get inconsistent results.
89 |     nats.counter.decrement write_subject
90 | 
91 |     nats.counter.get(write_subject).should eq -1_001
92 |   end
93 | end
94 | 


--------------------------------------------------------------------------------
/src/counter.cr:
--------------------------------------------------------------------------------
  1 | require "big"
  2 | require "big/json"
  3 | 
  4 | require "./nats"
  5 | require "./jetstream"
  6 | 
  7 | module NATS
  8 |   struct Counter
  9 |     def initialize(@nats : Client)
 10 |     end
 11 | 
 12 |     def set(subject : String, to value : Int) : Nil
 13 |       reset subject
 14 |       increment subject, by: value
 15 |     end
 16 | 
 17 |     def increment(subject : String, by delta : Int = 1) : BigInt
 18 |       response = @nats.request subject, headers: Headers{"Nats-Incr" => delta.to_s}
 19 | 
 20 |       unless response
 21 |         raise MissingCounter.new("No response from NATS, missing counter for subject: #{subject.inspect}")
 22 |       end
 23 | 
 24 |       pub_ack = JetStream::PubAck.from_json(response.data_string)
 25 | 
 26 |       if val = pub_ack.val
 27 |         val.to_big_i
 28 |       else
 29 |         raise Error.new("Missing value from NATS server response: #{response.data_string}")
 30 |       end
 31 |     end
 32 | 
 33 |     def decrement(subject, by delta : Int = 1) : BigInt
 34 |       increment subject, by: -delta
 35 |     end
 36 | 
 37 |     def increment!(subject : String, by delta : Int = 1) : Nil
 38 |       @nats.publish subject, headers: Headers{"Nats-Incr" => delta.to_s}
 39 |     end
 40 | 
 41 |     def decrement!(subject : String, by delta : Int = 1) : Nil
 42 |       @nats.publish subject, headers: Headers{"Nats-Incr" => (-delta).to_s}
 43 |     end
 44 | 
 45 |     def get(subject : String) : BigInt
 46 |       if stream = @nats.jetstream.stream.list(subject: subject).first?
 47 |         unless response = @nats.jetstream.stream.get_msg(stream.config.name, last_by_subject: subject)
 48 |           # There are is no message in the stream on that subject so, by
 49 |           # definition, the counter is 0.
 50 |           return 0.to_big_i
 51 |         end
 52 | 
 53 |         result = GetResponse.from_json(response.message.data_string)
 54 |         result.value
 55 |       else
 56 |         raise MissingCounter.new("No counter for subject: #{subject.inspect}")
 57 |       end
 58 |     end
 59 | 
 60 |     def reset(subject : String) : Nil
 61 |       # The counter could be fed by other streams, so we get the current value
 62 |       # and decrement by that before purging.
 63 |       # See https://github.com/nats-io/nats-architecture-and-design/blob/3994269ce71bb4dd69c8080b5fff6b4911b410c8/adr/ADR-49.md
 64 |       current_value = get(subject)
 65 |       decrement subject, by: current_value
 66 | 
 67 |       stream = @nats.jetstream.stream.list(subject: subject).first
 68 |       @nats.jetstream.stream.purge stream.config.name, subject
 69 |     end
 70 | 
 71 |     def create(name : String, subjects : Array(String), storage : NATS::JetStream::StreamConfig::Storage = :file)
 72 |       stream = @nats.jetstream.stream.create(
 73 |         name: name,
 74 |         subjects: subjects,
 75 |         storage: storage,
 76 |         allow_msg_counter: true,
 77 |         allow_direct: true,
 78 |       )
 79 | 
 80 |       Counter.new(@nats)
 81 |     end
 82 | 
 83 |     private struct GetResponse
 84 |       include JSON::Serializable
 85 | 
 86 |       @[JSON::Field(key: "val")]
 87 |       getter value : BigInt
 88 |     end
 89 | 
 90 |     class Error < NATS::Error
 91 |     end
 92 | 
 93 |     class MissingCounter < Error
 94 |     end
 95 |   end
 96 | 
 97 |   class Client
 98 |     def counter
 99 |       Counter.new(self)
100 |     end
101 |   end
102 | end
103 | 


--------------------------------------------------------------------------------
/src/jetstream/message.cr:
--------------------------------------------------------------------------------
 1 | require "../nats"
 2 | 
 3 | module NATS::JetStream
 4 |   # A `NATS::JetStream::Message` is very similar to a `NATS::Message` in that
 5 |   # it represents a piece of information published by a NATS client (not
 6 |   # necessarily _this_ NATS client, though). This `Message` type contains more
 7 |   # information, however, such as information about the stream and consumer
 8 |   # it came from, how many times it's been delivered, etc.
 9 |   struct Message
10 |     # The name of the stream this message was consumed from
11 |     getter stream : String
12 | 
13 |     # The name of the consumer we received this message from
14 |     getter consumer : String
15 | 
16 |     # The number of times this particular message has been delivered by this
17 |     # consumer, starting at 1
18 |     getter delivered_count : Int64
19 | 
20 |     # The position of this message within its stream
21 |     getter stream_seq : Int64
22 | 
23 |     # The position of this message within its consumer, including redeliveries
24 |     getter consumer_seq : Int64
25 | 
26 |     # When this message was originally published
27 |     getter timestamp : Time
28 | 
29 |     # How many messages follow this message for this consumer
30 |     getter pending : Int64
31 | 
32 |     # The message payload, encoded as binary. If you need text,
33 |     # use `data_string`.
34 |     #
35 |     # ```
36 |     # jetstream.subscribe consumer do |msg|
37 |     #   data = MessagePack.parse(msg.data)
38 |     # end
39 |     # ```
40 |     def data : Bytes
41 |       data_string.to_slice
42 |     end
43 | 
44 |     # :ditto:
45 |     def body : Bytes
46 |       data
47 |     end
48 | 
49 |     # The message payload, encoded as a UTF-8 string.
50 |     getter data_string : String
51 | 
52 |     # The original subject this message was published to, which can be (and
53 |     # most likely is) different from the subject it was delivered to
54 |     getter subject : String
55 | 
56 |     # The subject used for acknowledging this message
57 |     getter reply_to : String
58 | 
59 |     # Any headers that were published with this message, including ones
60 |     # interpreted by the NATS server, such as `Nats-Msg-Id` for message
61 |     # deduplication.
62 |     getter headers : Headers { Headers.new }
63 | 
64 |     # Instantiate a `NATS::JetStream::Message` based on a `NATS::Message`.
65 |     # Used by JetStream subscriptions to build `JetStream::Message`
66 |     # instances, since JetStream is a layer on top of core NATS.
67 |     def self.new(msg : ::NATS::Message)
68 |       # reply_to format:
69 |       # $JS.ACK.<stream>.<consumer>.<delivered count>.<stream sequence>.<consumer sequence>.<timestamp>.<pending messages>
70 |       if reply_to = msg.reply_to
71 |         # TODO: figure out if it's worth optimizing to avoid the array allocation
72 |         _jetstream, _ack, stream, consumer, delivered_count, stream_seq, consumer_seq, timestamp, pending_messages = reply_to.split('.')
73 |         new(
74 |           stream: stream,
75 |           consumer: consumer,
76 |           delivered_count: delivered_count.to_i64,
77 |           stream_seq: stream_seq.to_i64,
78 |           consumer_seq: consumer_seq.to_i64,
79 |           timestamp: Time::UNIX_EPOCH + timestamp.to_i64.nanoseconds,
80 |           pending: pending_messages.to_i64,
81 |           data_string: msg.data_string,
82 |           subject: msg.subject,
83 |           reply_to: reply_to,
84 |           headers: msg.headers,
85 |         )
86 |       else
87 |         raise InvalidJetStreamMessage.new("JetStream messages must have the reply_to field")
88 |       end
89 |     end
90 | 
91 |     def initialize(@stream, @consumer, @delivered_count, @stream_seq, @consumer_seq, @timestamp, @pending, @data_string, @subject, @reply_to, @headers)
92 |     end
93 | 
94 |     class InvalidJetStreamMessage < Exception
95 |     end
96 |   end
97 | end
98 | 


--------------------------------------------------------------------------------
/src/jetstream/pull_subscription.cr:
--------------------------------------------------------------------------------
  1 | require "../nats"
  2 | require "./consumer"
  3 | require "./message"
  4 | 
  5 | module NATS::JetStream
  6 |   class PullSubscription
  7 |     getter consumer : Consumer
  8 |     @nats : NATS::Client
  9 | 
 10 |     def initialize(@consumer, @nats)
 11 |     end
 12 | 
 13 |     def fetch(timeout : Time::Span = 2.seconds)
 14 |       fetch(1, timeout: timeout).first?
 15 |     end
 16 | 
 17 |     def fetch(message_count : Int, timeout : Time::Span = 2.seconds, no_wait : Bool = false, max_bytes : Int? = nil) : Enumerable(Message)
 18 |       # We have to reimplement request/reply here because we get N replies
 19 |       # for 1 request, which NATS request/reply does not support.
 20 |       LOG.trace { "Creating channel" }
 21 |       channel = Channel(Message).new(message_count)
 22 |       deliver_subject = "_INBOX.#{NUID.next}"
 23 |       LOG.trace { "Sending subscription" }
 24 |       subscription = @nats.subscribe deliver_subject do |msg, sub|
 25 |         # If there isn't a reply-to, we're probably getting an update about
 26 |         # some logistics pertaining to this pull subscription.
 27 |         if (headers = msg.headers) && (status = headers["Status"]?) && status.starts_with?("409")
 28 |           sub.close
 29 |         elsif msg.reply_to.presence
 30 |           # We can only receive messages that can be replied to because that's
 31 |           # how we ack them.
 32 |           channel.send Message.new(msg)
 33 |         else
 34 |           raise InternalError.new("Found a bug in NATS pull subscriptions. Please check the issues at https://github.com/jgaskins/nats/issues and, if there is not one open yet, please open one with this stack trace.")
 35 |         end
 36 |       end
 37 | 
 38 |       @nats.publish "$JS.API.CONSUMER.MSG.NEXT.#{consumer.stream_name}.#{consumer.name}",
 39 |         message: {
 40 |           expires: {(timeout - 100.milliseconds).total_nanoseconds, 0}
 41 |             .max
 42 |             .to_i64,
 43 |           batch: message_count,
 44 |         }.to_json,
 45 |         reply_to: deliver_subject
 46 |       @nats.flush!
 47 | 
 48 |       msgs = Array(Message).new(initial_capacity: message_count)
 49 |       total_timeout = timeout
 50 |       finish_by = Time.monotonic + timeout
 51 | 
 52 |       message_count.times do |i|
 53 |         LOG.trace { "Waiting for message #{i}" }
 54 |         select
 55 |         when msg = channel.receive
 56 |           LOG.trace { "received" }
 57 |           msgs << msg
 58 |         when timeout(finish_by - Time.monotonic)
 59 |           LOG.trace { "timed out" }
 60 |           break
 61 |         end
 62 |       end
 63 |       @nats.unsubscribe subscription
 64 | 
 65 |       msgs
 66 |     end
 67 | 
 68 |     # Acknowledge the given message and request the next in a single round
 69 |     # trip to the server to save latency.
 70 |     #
 71 |     # ```
 72 |     # pull = js.pull_subscribe(consumer)
 73 |     # # Poll for messages until we get one
 74 |     # until msg = pull.fetch(timeout: 30.seconds)
 75 |     # end
 76 |     # loop do
 77 |     # end
 78 |     # ```
 79 |     def ack_next(msg : Message, timeout : Time::Span = 2.seconds)
 80 |       # ack_next(msg, 1, timeout, no_wait).first?
 81 |       inbox = "ack-next.#{NUID.next}"
 82 |       channel = Channel(Message).new(1)
 83 | 
 84 |       begin
 85 |         sub = @nats.subscribe inbox do |msg|
 86 |           channel.send Message.new(msg)
 87 |         end
 88 |         @nats.unsubscribe sub, max_messages: 1
 89 | 
 90 |         @nats.publish(msg.reply_to, "+NXT 1", reply_to: inbox)
 91 | 
 92 |         select
 93 |         when reply = channel.receive
 94 |           reply
 95 |         when timeout(timeout)
 96 |           @nats.unsubscribe sub
 97 |           nil
 98 |         end
 99 |       end
100 |     end
101 | 
102 |     # Acknowledge the given message and request the next `count` messages in
103 |     # a single round trip to the server to save latency.
104 |     def ack_next(msg : Message, count : Int, timeout : Time::Span = 2.seconds, no_wait : Bool = false)
105 |       # This is an async ack, and then we fetch synchronously
106 |       nats.jetstream.ack msg
107 |       fetch(count, timeout: timeout)
108 |     end
109 | 
110 |     class InternalError < Error
111 |     end
112 |   end
113 | end
114 | 


--------------------------------------------------------------------------------
/src/jetstream/consumers.cr:
--------------------------------------------------------------------------------
  1 | require "../nats"
  2 | require "./consumer_config"
  3 | require "./consumer"
  4 | require "./consumer_list_response"
  5 | 
  6 | module NATS::JetStream
  7 |   # A NATS JetStream consumer is a message index sourced from a stream.
  8 |   # It can apply additional filters and records which messages are pending,
  9 |   # acknowledged, etc, at the consumer layer.
 10 |   struct Consumers
 11 |     def initialize(@nats : ::NATS::Client)
 12 |     end
 13 | 
 14 |     # Create a consumer for the given stream with the given properties,
 15 |     # which are passed unmodified to `NATS::JetStream::Consumer.new`.
 16 |     def create(
 17 |       stream_name : String,
 18 |       deliver_policy : ConsumerConfig::DeliverPolicy = :all,
 19 |       ack_policy : ConsumerConfig::AckPolicy = :explicit,
 20 |       **properties,
 21 |     ) : Consumer
 22 |       consumer_config = ConsumerConfig.new(
 23 |         **properties,
 24 |         deliver_policy: deliver_policy,
 25 |         ack_policy: ack_policy,
 26 |       )
 27 |       create_consumer = {stream_name: stream_name, config: consumer_config}
 28 |       if durable_name = consumer_config.durable_name
 29 |         create_consumer_subject = "$JS.API.CONSUMER.DURABLE.CREATE.#{stream_name}.#{durable_name}"
 30 |       else
 31 |         name = @nats.nuid.next
 32 |         create_consumer_subject = "$JS.API.CONSUMER.CREATE.#{stream_name}.#{name}"
 33 |       end
 34 | 
 35 |       unless response = @nats.request create_consumer_subject, create_consumer.to_json
 36 |         raise Error.new("Did not receive a response from NATS JetStream")
 37 |       end
 38 | 
 39 |       case parsed = (Consumer | ErrorResponse).from_json String.new(response.body)
 40 |       in Consumer
 41 |         parsed
 42 |       in ErrorResponse
 43 |         raise Error.new("#{parsed.error.description} (#{parsed.error.code})")
 44 |       end
 45 |     end
 46 | 
 47 |     # Returns a paginated list of consumers for the specified stream.
 48 |     def list(stream : JetStream::Stream)
 49 |       list stream.config.name
 50 |     end
 51 | 
 52 |     # Returns a paginated list of consumers for the stream with the
 53 |     # specified name.
 54 |     def list(stream_name : String)
 55 |       if consumers_response = @nats.request "$JS.API.CONSUMER.LIST.#{stream_name}"
 56 |         ConsumerListResponse.from_json(String.new(consumers_response.body))
 57 |       else
 58 |         raise "whoops"
 59 |       end
 60 |     end
 61 | 
 62 |     # Return the consumer with the specified `name` associated with the
 63 |     # given stream, yielding to the block if the consumer does not exist
 64 |     def info!(stream_name : String, name : String) : Consumer
 65 |       info(stream_name, name) do
 66 |         raise ArgumentError.new("Consumer #{name.inspect} not found for stream #{stream_name.inspect}")
 67 |       end
 68 |     end
 69 | 
 70 |     def info(stream_name : String, name : String) : Consumer?
 71 |       info(stream_name, name) { nil }
 72 |     end
 73 | 
 74 |     # Return the consumer with the specified `name` associated with the
 75 |     # given stream, yielding to the block if the consumer does not exist
 76 |     def info(stream_name : String, name : String, &)
 77 |       if consumer_response = @nats.request "$JS.API.CONSUMER.INFO.#{stream_name}.#{name}"
 78 |         case parsed = (Consumer | ErrorResponse).from_json(String.new(consumer_response.body))
 79 |         in Consumer
 80 |           parsed
 81 |         in ErrorResponse
 82 |           if parsed.error.err_code.consumer_not_found?
 83 |             yield
 84 |           else
 85 |             raise Error.new(parsed.error.description)
 86 |           end
 87 |         end
 88 |       else
 89 |         raise "no info for #{name.inspect} (stream #{stream_name.inspect})"
 90 |       end
 91 |     end
 92 | 
 93 |     # Delete the given consumer for the given stream
 94 |     def delete(consumer : JetStream::Consumer)
 95 |       delete consumer.stream_name, consumer.name
 96 |     end
 97 | 
 98 |     # Delete the given consumer for the given stream
 99 |     def delete(stream : JetStream::Stream, consumer : JetStream::Consumer)
100 |       delete stream.config.name, consumer.name
101 |     end
102 | 
103 |     # Delete the consumer with the given name associated with the stream
104 |     # with the given name.
105 |     def delete(stream : String, consumer : String)
106 |       @nats.request "$JS.API.CONSUMER.DELETE.#{stream}.#{consumer}"
107 |     end
108 |   end
109 | 
110 |   deprecate_api_v1 Consumers
111 | end
112 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | # NATS
  2 | 
  3 | NATS is a message broker for distributed systems.
  4 | 
  5 | ## Installation
  6 | 
  7 | 1. Add the dependency to your `shard.yml`:
  8 | 
  9 |    ```yaml
 10 |    dependencies:
 11 |      nats:
 12 |        github: jgaskins/nats
 13 |    ```
 14 | 
 15 | 2. Run `shards install`
 16 | 
 17 | ## Usage
 18 | 
 19 | You can use NATS in a publish/subscribe or request/reply paradigm.
 20 | 
 21 | ### Publish/Subscribe
 22 | 
 23 | For publish/subscribe, let's consider the following class to be shared, representing an event that will be published by one service and picked up by another:
 24 | 
 25 | ```crystal
 26 | require "uuid"
 27 | require "json"
 28 | require "uuid/json"
 29 | 
 30 | struct UserRegisteredEvent
 31 |   include JSON::Serializable
 32 | 
 33 |   getter id : UUID
 34 |   getter email : String
 35 |   getter name : String
 36 | 
 37 |   def initialize(@id, @email, @name)
 38 |   end
 39 | end
 40 | ```
 41 | 
 42 | In one service, we can subscribe to a subject that will be sent all of the events pertaining to a user registering:
 43 | 
 44 | ```crystal
 45 | require "nats"
 46 | 
 47 | nats = NATS::Client.new(URI.parse(ENV["NATS_URL"]))
 48 | 
 49 | # Subscribe to all messages on "customers.registration" with an optional queue
 50 | # group. A message will only be delivered to a single client in a given queue
 51 | # group.
 52 | nats.subscribe "customers.registration", queue_group: "cart-service" do |msg|
 53 |   new_user = UserRegisteredEvent.from_json(msg.body_io)
 54 | 
 55 |   # This message represents that a new customer has registered, presumably sent
 56 |   # by our identity/authentication/user service. We create a record for this
 57 |   # customer in our own database so we don't always need to request the info
 58 |   # from that service.
 59 |   UserQuery.new.create_from_message(new_user)
 60 | end
 61 | 
 62 | # Accept wildcard messages. This would match:
 63 | # - orders.commercial.fulfilled
 64 | # - orders.individual.fulfilled
 65 | nats.subscribe "orders.*.shipped", queue_group: "cart-service" do |msg|
 66 |   # ...
 67 | end
 68 | 
 69 | # Since the subscribe blocks above do not block execution, we need to keep the
 70 | # main fiber from exiting. In a real-world app, you might trap a TERM/INT signal
 71 | # to allow the app to close the connection gracefully.
 72 | sleep
 73 | ```
 74 | 
 75 | And then to publish on those topics:
 76 | 
 77 | ```crystal
 78 | require "nats"
 79 | 
 80 | nats = NATS::Client.new(URI.parse(ENV["NATS_URL"]))
 81 | 
 82 | # We can publish a message with a given subject. In this example, we'll
 83 | # publish a message saying Jolene has registered.
 84 | nats.publish "customers.registration", UserRegisteredEvent.new(
 85 |   id: UUID.random,
 86 |   name: "Jolene",
 87 |   email: "jolene@gonnatakeyourman.com",
 88 | )
 89 | 
 90 | nats.close
 91 | ```
 92 | 
 93 | ### Request/Reply
 94 | 
 95 | Let's consider an orders service that we may want to send requests to.
 96 | 
 97 | ```crystal
 98 | require "uuid"
 99 | require "json"
100 | require "uuid/json"
101 | require "db"
102 | 
103 | module Orders
104 |   struct Get
105 |     include JSON::Serializable
106 | 
107 |     getter id : UUID
108 | 
109 |     def initialize(@id)
110 |     end
111 |   end
112 | end
113 | 
114 | struct Order
115 |   include DB::Serializable
116 |   include JSON::Serializable
117 | 
118 |   getter id : UUID
119 |   getter address : String
120 |   getter city : String
121 |   getter state : String
122 |   getter postal_code : String
123 | end
124 | ```
125 | 
126 | #### Define the request handler
127 | 
128 | ```crystal
129 | require "nats"
130 | 
131 | nats = NATS::Client.new(URI.parse(ENV["NATS_URL"]))
132 | 
133 | # Subscribe to the subject that the request will be sent to
134 | nats.subscribe "orders.get", do |msg|
135 |   request = Orders::Get.from_json(msg.body_io)
136 | 
137 |   order = OrderQuery.new.with_id(request.id)
138 | 
139 |   nats.reply msg, order.to_json
140 | end
141 | ```
142 | 
143 | #### Sending the request
144 | 
145 | ```crystal
146 | require "nats"
147 | 
148 | nats = NATS::Client.new(URI.parse(ENV["NATS_URL"]))
149 | 
150 | # Send the request to the subject it is expected to be received on:
151 | order = nats.request "orders.get",
152 |   message: Orders::Get.new(order_id).to_json,
153 |   timeout: 5.seconds # A timeout must be specified
154 | 
155 | pp order
156 | ```
157 | 
158 | ## Development
159 | 
160 | TODO: Write development instructions here
161 | 
162 | ## Contributing
163 | 
164 | 1. Fork it (<https://github.com/jgaskins/nats/fork>)
165 | 2. Create your feature branch (`git checkout -b my-new-feature`)
166 | 3. Commit your changes (`git commit -am 'Add some feature'`)
167 | 4. Push to the branch (`git push origin my-new-feature`)
168 | 5. Create a new Pull Request
169 | 
170 | ## Contributors
171 | 
172 | - [Jamie Gaskins](https://github.com/jgaskins) - creator and maintainer
173 | 


--------------------------------------------------------------------------------
/src/jetstream/stream_config.cr:
--------------------------------------------------------------------------------
  1 | require "./entity"
  2 | require "./stream_source"
  3 | 
  4 | module NATS::JetStream
  5 |   struct StreamConfig < Entity
  6 |     # The `Storage` parameter tells the NATS server how to store the
  7 |     # messages in the stream.
  8 |     enum Storage
  9 |       # Store messages in memory. This is the fastest, but is not durable.
 10 |       # If the NATS server is restarted for any reason, the stream will
 11 |       # be dropped. Using this option may also increase the amount of
 12 |       # memory required by your NATS server. Use with caution.
 13 |       Memory
 14 | 
 15 |       # Store messages on disk. Always use this if your system depends on
 16 |       # 100% delivery.
 17 |       File
 18 |     end
 19 | 
 20 |     # The `RetentionPolicy` tells the NATS server when messages can be
 21 |     # discarded. Your options are to wait until the a quantity/volume/time
 22 |     # limit has been reached, _all_ consumers have acknowledged, or _any_
 23 |     # consumers have acknowledged.
 24 |     #
 25 |     # ```
 26 |     # jetstream.stream.create(
 27 |     #   # ...
 28 |     #   retention: :workqueue,
 29 |     # )
 30 |     # ```
 31 |     enum RetentionPolicy
 32 |       # Discard messages when the stream has reached the limit of either
 33 |       # the number of messages or the total stream size in bytes, or the
 34 |       # message's max age has passed.
 35 |       Limits
 36 | 
 37 |       # Discard a message when all subscribed consumers have acknowledged
 38 |       # it to guarantee delivery but not keep the message in memory. This
 39 |       # is the default behavior of AMQP.
 40 |       Interest
 41 | 
 42 |       # Discard a message when the first consumer has acknowledged it, as
 43 |       # in a work queue like Sidekiq.
 44 |       Workqueue
 45 |     end
 46 | 
 47 |     # The `DiscardPolicy` tells the NATS server which end of the stream to
 48 |     # truncate when the stream is full — should we start dropping old
 49 |     # messages or avoid adding new ones?
 50 |     enum DiscardPolicy
 51 |       # Drop old messages when the stream has reached a count or volume
 52 |       # limit
 53 |       Old
 54 | 
 55 |       # Don't add new messages until old ones are discarded
 56 |       New
 57 |     end
 58 | 
 59 |     struct Placement < Entity
 60 |       getter cluster : String?
 61 |       getter tags : Array(String) { %w[] }
 62 | 
 63 |       def initialize(@cluster = nil, @tags = nil)
 64 |       end
 65 |     end
 66 | 
 67 |     struct Republish < Entity
 68 |       @[JSON::Field(key: "src")]
 69 |       getter source : String?
 70 |       @[JSON::Field(key: "dest")]
 71 |       getter destination : String
 72 |       getter? headers_only : Bool?
 73 | 
 74 |       def initialize(*, @source : String? = nil, @destination, @headers_only = nil)
 75 |       end
 76 |     end
 77 | 
 78 |     # Name of this stream
 79 |     getter name : String
 80 |     getter description : String?
 81 | 
 82 |     # Which subjects this stream will listen for.
 83 |     getter subjects : Array(String) { [] of String }
 84 |     getter storage : Storage
 85 |     @[JSON::Field(converter: ::NATS::JetStream::NanosecondsConverter)]
 86 |     getter max_age : Time::Span?
 87 |     getter max_bytes : Int64?
 88 |     getter max_msg_size : Int32?
 89 |     getter max_msgs : Int64?
 90 |     getter max_msgs_per_subject : Int64?
 91 |     getter max_consumers : Int32?
 92 |     getter? no_ack : Bool?
 93 |     @[JSON::Field(key: "num_replicas")]
 94 |     getter replicas : Int32
 95 |     getter retention : RetentionPolicy?
 96 |     getter discard : DiscardPolicy?
 97 |     getter placement : Placement?
 98 |     getter mirror : StreamSource?
 99 |     getter sources : Array(StreamSource) { [] of StreamSource }
100 |     @[JSON::Field(converter: ::NATS::JetStream::NanosecondsConverter)]
101 |     getter duplicate_window : Time::Span?
102 |     @[JSON::Field(key: "allow_rollup_hdrs")]
103 |     getter? allow_rollup_headers : Bool?
104 |     getter? deny_purge : Bool?
105 |     getter? deny_delete : Bool?
106 |     getter? sealed : Bool?
107 |     getter? allow_direct : Bool?
108 |     getter? mirror_direct : Bool?
109 |     getter? discard_new_per_subject : Bool?
110 |     getter? allow_msg_ttl : Bool?
111 |     getter? allow_msg_counter : Bool?
112 |     getter republish : Republish?
113 |     getter compression : Compression
114 | 
115 |     def initialize(
116 |       @name,
117 |       @subjects = nil,
118 |       @description = nil,
119 |       @max_age = nil,
120 |       @max_bytes = nil,
121 |       @max_msg_size = nil,
122 |       @max_msgs = nil,
123 |       @max_msgs_per_subject = nil,
124 |       @max_consumers = nil,
125 |       @no_ack = false,
126 |       @replicas = 1,
127 |       @retention : RetentionPolicy? = nil,
128 |       @allow_rollup_headers = nil,
129 |       @deny_delete = nil,
130 |       @allow_direct = nil,
131 |       @mirror_direct = nil,
132 |       @republish = nil,
133 |       @placement = nil,
134 |       @mirror = nil,
135 |       @sources = nil,
136 |       @discard_new_per_subject = nil,
137 |       @discard : DiscardPolicy? = nil,
138 |       @allow_msg_ttl = false,
139 |       @allow_msg_counter = false,
140 |       @storage : Storage = :file,
141 |       @compression = :none,
142 |     )
143 |     end
144 | 
145 |     enum Compression
146 |       None = 0
147 |       S2   = 1
148 |     end
149 |   end
150 | 
151 |   deprecate_api_v1 StreamConfig
152 | end
153 | 


--------------------------------------------------------------------------------
/src/jetstream/consumer_config.cr:
--------------------------------------------------------------------------------
  1 | require "./entity"
  2 | 
  3 | module NATS::JetStream
  4 |   struct ConsumerConfig < Entity
  5 |     # How messages should be acknowledged: none, all, or explicit
  6 |     getter ack_policy : AckPolicy
  7 |     # How long to allow messages to remain un-acknowledged before attempting redelivery
  8 |     @[JSON::Field(converter: ::NATS::JetStream::NanosecondsConverter)]
  9 |     getter ack_wait : Time::Span?
 10 |     # The initial starting mode of the consumer: all, last, new, by-start_sequence or by_start_time
 11 |     getter deliver_policy : DeliverPolicy
 12 |     # The subject to deliver observed messages, when not set, a pull-based Consumer is created
 13 |     getter deliver_subject : String?
 14 |     # The name of the Consumer, specifying this will persist the consumer to the NATS server
 15 |     getter durable_name : String?
 16 | 
 17 |     getter deliver_group : String?
 18 |     getter description : String?
 19 |     getter max_waiting : Int64?
 20 |     @[JSON::Field(converter: ::NATS::JetStream::NanosecondsConverter)]
 21 |     getter idle_heartbeat : Time::Span?
 22 |     getter? flow_control : Bool { false }
 23 |     getter? headers_only : Bool { false }
 24 | 
 25 |     # Apparently we're not supposed to use this in clients
 26 |     # See https://github.com/nats-io/nats-server/blob/3aa8e63b290ac4ba1c99193827b3f66ad5679904/server/consumer.go#L70-L71
 27 |     # getter? direct : Bool = false
 28 | 
 29 |     # When consuming from a Stream with many subjects, or wildcards, select only a specific incoming subjects, supports wildcards
 30 |     getter filter_subject : String?
 31 | 
 32 |     # When consuming from a Stream with many subjects, or wildcards, select only a specific incoming subjects, supports wildcards
 33 |     getter filter_subjects : Array(String)?
 34 | 
 35 |     # Maximum number of times a message will be delivered via this consumer. Use this to avoid poison pills crashing all your services forever.
 36 |     getter max_deliver : Int64?
 37 |     # When first consuming messages from the Stream start at this particular message in the set
 38 |     getter opt_start_seq : Int64?
 39 |     # OptStartTime	When first consuming messages from the Stream start with messages on or after this time
 40 |     getter opt_start_time : Time?
 41 |     # How messages are sent: `instant` (default) or `original`
 42 |     getter replay_policy : ReplayPolicy
 43 |     # What percentage of acknowledgements should be samples for observability, 0-100
 44 |     getter sample_frequency : String?
 45 |     # The rate of message delivery in bits per second
 46 |     getter rate_limit_bps : UInt64?
 47 |     # The maximum number of messages without acknowledgement that can be outstanding, once this limit is reached message delivery will be suspended
 48 |     getter max_ack_pending : Int64?
 49 | 
 50 |     @[JSON::Field(converter: ::NATS::JetStream::NanosecondsConverter)]
 51 |     getter inactive_threshold : Time::Span?
 52 | 
 53 |     @[JSON::Field(key: "num_replicas")]
 54 |     getter replicas : Int32 = 0
 55 |     @[JSON::Field(key: "mem_storage")]
 56 |     getter? memory_storage : Bool?
 57 | 
 58 |     # // Pull based options.
 59 |     # MaxRequestBatch    int           `json:"max_batch,omitempty"`
 60 |     # MaxRequestExpires  time.Duration `json:"max_expires,omitempty"`
 61 |     # MaxRequestMaxBytes int           `json:"max_bytes,omitempty"`
 62 |     # The maximum number of messages that can be requested from a pull consumer
 63 |     @[JSON::Field(key: "max_batch")]
 64 |     getter max_request_batch : Int32?
 65 |     # The
 66 |     @[JSON::Field(key: "max_expires", converter: ::NATS::JetStream::NanosecondsConverter)]
 67 |     getter max_request_expires : Time::Span?
 68 |     @[JSON::Field(key: "max_bytes")]
 69 |     getter max_request_max_bytes : Int32?
 70 | 
 71 |     def initialize(
 72 |       @deliver_subject = nil,
 73 |       @durable_name = nil,
 74 |       @ack_policy : AckPolicy = :explicit,
 75 |       @deliver_policy : DeliverPolicy = :all,
 76 |       @replay_policy : ReplayPolicy = :instant,
 77 |       @ack_wait = nil,
 78 |       @filter_subject = nil,
 79 |       @filter_subjects = nil,
 80 |       max_deliver = nil,
 81 |       @opt_start_seq = nil,
 82 |       @sample_frequency = nil,
 83 |       @opt_start_time = nil,
 84 |       @rate_limit_bps = nil,
 85 |       max_ack_pending : Int? = nil,
 86 |       max_waiting : Int? = nil,
 87 |       @idle_heartbeat = nil,
 88 |       @flow_control = nil,
 89 |       @headers_only = nil,
 90 |       @deliver_group = durable_name,
 91 |       @max_request_batch = nil,
 92 |       @max_request_expires = nil,
 93 |       @max_request_max_bytes = nil,
 94 |       @replicas = 0,
 95 |       @memory_storage = nil,
 96 |       @inactive_threshold = nil,
 97 |     )
 98 |       @max_deliver = max_deliver.try(&.to_i64)
 99 |       @max_ack_pending = max_ack_pending.to_i64 if max_ack_pending
100 |       @max_waiting = max_waiting.try(&.to_i64)
101 |     end
102 | 
103 |     # The way this consumer expects messages to be acknowledged.
104 |     #
105 |     # See [AckPolicy in the NATS server code](https://github.com/nats-io/nats-server/blob/3aa8e63b290ac4ba1c99193827b3f66ad5679904/server/consumer.go#L136-L143)
106 |     enum AckPolicy
107 |       # No acknowledgements are required. All messages are considered
108 |       # acknowledged on delivery.
109 |       None
110 | 
111 |       # Acknowledging a message acknowledges all messages that came before
112 |       # it.
113 |       All
114 | 
115 |       # Every message must be acknowledged individually. This is the
116 |       # default.
117 |       Explicit
118 |     end
119 | 
120 |     # Where to begin consuming messages from a stream.
121 |     #
122 |     # See [DeliverPolicy in the NATS server code](https://github.com/nats-io/nats-server/blob/3aa8e63b290ac4ba1c99193827b3f66ad5679904/server/consumer.go#L105-L120)
123 |     enum DeliverPolicy
124 |       # Deliver _all_ messages from a stream via this consumer
125 |       All
126 | 
127 |       # Start from the current last message in the stream when this
128 |       # consumer was created
129 |       Last
130 | 
131 |       # Start _after_ the current last message in the stream when this
132 |       # consumer was created. This is different from `Last` in that it
133 |       # will not begin delivering messages until more are published.
134 |       New
135 | 
136 |       # Start delivery at the sequence in the stream denoted by
137 |       # `opt_start_seq`. `opt_start_seq` is _required_ when this
138 |       # `DeliverPolicy` is used.
139 |       ByStartSequence
140 | 
141 |       # Start delivery at the first message whose `timestamp` is equal to
142 |       # or later than `opt_start_time`. `opt_start_time` is _required
143 |       # when this `DeliverPolicy` is used.
144 |       ByStartTime
145 | 
146 |       # Similar to `Last`, but on a per-subject basis.
147 |       LastPerSubject
148 | 
149 |       # If you've got this set, something's probably borked. This value
150 |       # only exists in this client because [the server can send it](https://github.com/nats-io/nats-server/blob/3aa8e63b290ac4ba1c99193827b3f66ad5679904/server/consumer.go#L118-L119).
151 |       Undefined
152 |     end
153 | 
154 |     # A consumer's `replay_policy` is the pace at which to replay messages
155 |     # from a stream.
156 |     #
157 |     # See [ReplayPolicy in the NATS server code](https://github.com/nats-io/nats-server/blob/3aa8e63b290ac4ba1c99193827b3f66ad5679904/server/consumer.go#L157-L162)
158 |     enum ReplayPolicy
159 |       # Tells the NATS server to deliver messages immediately
160 |       Instant
161 | 
162 |       # Tells the NATS server to deliver messages at the rate they were
163 |       # originally published.
164 |       Original
165 |     end
166 |   end
167 | 
168 |   deprecate_api_v1 ConsumerConfig
169 | end
170 | 


--------------------------------------------------------------------------------
/spec/services_spec.cr:
--------------------------------------------------------------------------------
  1 | require "./spec_helper"
  2 | require "wait_group"
  3 | 
  4 | require "../src/services"
  5 | 
  6 | nats = NATS::Client.new
  7 |   .on_error { |ex| pp ex }
  8 | 
  9 | describe NATS::Services do
 10 |   it "creates a service" do
 11 |     name = "test-service-#{UUID.v7}"
 12 |     svc = nats.services.add name,
 13 |       version: "0.1.0",
 14 |       description: "does a thing"
 15 | 
 16 |     svc.name.should eq name
 17 |   end
 18 | 
 19 |   it "creates endpoints" do
 20 |     name = "test-endpoint-#{UUID.v7}"
 21 |     svc = nats.services.add name,
 22 |       version: "0.1.0",
 23 |       description: "does a thing"
 24 |     root = svc.add_group(name)
 25 |     root.add_endpoint "upcase" do |request|
 26 |       nats.reply request, request.data_string.upcase
 27 |     end
 28 |     root.add_endpoint "downcase" do |request|
 29 |       nats.reply request, request.data_string.downcase
 30 |     end
 31 | 
 32 |     unless response = nats.request "#{name}.upcase", "hello"
 33 |       raise "Did not receive a response from the endpoint"
 34 |     end
 35 |     response.data_string.should eq "HELLO"
 36 |     unless response = nats.request "#{name}.downcase", "HELLO"
 37 |       raise "Did not receive a response from the endpoint"
 38 |     end
 39 |     response.data_string.should eq "hello"
 40 |   end
 41 | 
 42 |   it "cannot create an endpoint with an invalid name" do
 43 |     name = "test-endpoint-#{UUID.v7}"
 44 |     svc = nats.services.add name,
 45 |       version: "0.1.0",
 46 |       description: "does a thing"
 47 |     root = svc.add_group(name)
 48 |     expect_raises ArgumentError do
 49 |       root.add_endpoint "get.*" do |request|
 50 |         nats.reply request, request.data_string.upcase
 51 |       end
 52 |     end
 53 |   end
 54 | 
 55 |   it "responds to pings across all services" do
 56 |     name = "test-ping-#{UUID.v7}"
 57 |     svc = nats.services.add name,
 58 |       version: "0.1.0",
 59 |       description: "does a thing"
 60 | 
 61 |     nats.request("$SRV.PING", "").should_not be_nil
 62 |   end
 63 | 
 64 |   it "responds to pings at the service level" do
 65 |     name = "test-ping-service-#{UUID.v7}"
 66 |     svc = nats.services.add name,
 67 |       version: "0.1.0",
 68 |       description: "does a thing"
 69 | 
 70 |     nats.request("$SRV.PING.#{name}", "").should_not be_nil
 71 |   end
 72 | 
 73 |   it "responds to pings at the service id level" do
 74 |     name = "test-ping-service-id-#{UUID.v7}"
 75 |     svc = nats.services.add name,
 76 |       version: "0.1.0",
 77 |       description: "does a thing"
 78 | 
 79 |     nats.request("$SRV.PING.#{name}.#{svc.id}", "").should_not be_nil
 80 |   end
 81 | 
 82 |   it "responds with stats across all services" do
 83 |     name = "test-stats-#{UUID.v7}"
 84 |     svc = nats.services.add name,
 85 |       version: "0.1.0",
 86 |       description: "does a thing"
 87 | 
 88 |     nats.request("$SRV.STATS", "").should_not be_nil
 89 |   end
 90 | 
 91 |   it "responds with stats for the service" do
 92 |     name = "test-stats-service-#{UUID.v7}"
 93 |     svc = nats.services.add name,
 94 |       version: "0.1.0",
 95 |       description: "does a thing"
 96 |     group = svc.add_group name
 97 |     group.add_endpoint "foo" do |request|
 98 |       nats.reply request, "stuff"
 99 |     end
100 |     nats.request "#{name}.foo", ""
101 | 
102 |     unless response = nats.request("$SRV.STATS.#{name}", "")
103 |       raise "Did not receive a response from the endpoint"
104 |     end
105 |     stats = JSON.parse(response.data_string)
106 | 
107 |     stats["endpoints"][0]["num_requests"].should eq 1
108 |   end
109 | 
110 |   it "responds with stats for the service with the given id" do
111 |     name = "test-stats-service-id-#{UUID.v7}"
112 |     svc = nats.services.add name,
113 |       version: "0.1.0",
114 |       description: "does a thing"
115 |     group = svc.add_group name
116 |     group.add_endpoint "foo" do |request|
117 |       nats.reply request, "stuff"
118 |     end
119 |     nats.request "#{name}.foo", ""
120 | 
121 |     unless response = nats.request("$SRV.STATS.#{name}.#{svc.id}", "")
122 |       raise "Did not receive a response from the endpoint"
123 |     end
124 |     stats = JSON.parse(response.data_string)
125 | 
126 |     stats["endpoints"][0]["num_requests"].should eq 1
127 |   end
128 | 
129 |   it "responds with info for all services" do
130 |     name = "test-info-service-#{UUID.v7}"
131 |     svc = nats.services.add name,
132 |       version: "0.1.0",
133 |       description: "does a thing"
134 | 
135 |     nats.request("$SRV.INFO", "").should_not be_nil
136 |   end
137 | 
138 |   it "responds with info for this specific service" do
139 |     name = "test-info-service-id-#{UUID.v7}"
140 |     svc = nats.services.add name,
141 |       version: "0.1.0",
142 |       description: "does a thing"
143 | 
144 |     unless response = nats.request("$SRV.INFO.#{name}", "")
145 |       raise "Did not receive a response from the endpoint"
146 |     end
147 |     info = JSON.parse(response.data_string)
148 | 
149 |     info["type"].should eq "io.nats.micro.v1.info_response"
150 |     info["name"].should eq name
151 |     info["id"].should eq svc.id
152 |     info["description"].should eq "does a thing"
153 |     info["endpoints"].raw.should be_a Array(JSON::Any)
154 |   end
155 | 
156 |   it "responds with info for this service with the specific id" do
157 |     name = "test-info-service-id-#{UUID.v7}"
158 |     svc = nats.services.add name,
159 |       version: "0.1.0",
160 |       description: "does a thing"
161 | 
162 |     unless response = nats.request("$SRV.INFO.#{name}.#{svc.id}", "")
163 |       raise "Did not receive a response from the endpoint"
164 |     end
165 |     info = JSON.parse(response.data_string)
166 | 
167 |     info["type"].should eq "io.nats.micro.v1.info_response"
168 |   end
169 | 
170 |   it "responds with Nats-Service-Error and Nats-Service-Error-Code if an exception is raised in the block" do
171 |     name = "test-service-errors-#{UUID.v7}"
172 |     svc = nats.services.add name,
173 |       version: "0.1.0",
174 |       description: "does a thing"
175 |     group = svc.add_group name
176 |     endpoint = group.add_endpoint "oops" do
177 |       raise "hell"
178 |     end
179 | 
180 |     unless response = nats.request("#{name}.oops", "")
181 |       raise "Did not receive a response from the endpoint"
182 |     end
183 | 
184 |     response.headers["Nats-Service-Error-Code"].should eq "500"
185 |     response.headers["Nats-Service-Error"].should eq "hell"
186 |     endpoint.total_errors.should eq 1
187 |     endpoint.last_error.should eq "hell"
188 |   end
189 | 
190 |   it "allows nested groups" do
191 |     name = "test-nested-groups-#{UUID.v7}"
192 |     svc = nats.services.add name,
193 |       version: "0.1.0",
194 |       description: "does a thing"
195 | 
196 |     # This also tests that we can pass a block to add_group, so that's neat
197 |     svc.add_group name do |group|
198 |       group.add_group "a" do |a|
199 |         a.add_endpoint "stuff" do |msg|
200 |           nats.reply msg, "yep"
201 |         end
202 |       end
203 |     end
204 | 
205 |     nats.request("#{name}.a.stuff", "")
206 |       .try(&.data_string)
207 |       .should eq "yep"
208 |   end
209 | 
210 |   it "provides for error replies" do
211 |     name = "test-error-replies-#{UUID.v7}"
212 |     svc = nats.services.add name,
213 |       version: "0.1.0",
214 |       description: "does a thing"
215 |     subject = "#{name}.call"
216 |     svc.add_endpoint "lol", subject: subject do |request|
217 |       svc.error_reply request, "omg",
218 |         error: "oops",
219 |         error_code: 555
220 |     end
221 | 
222 |     unless response = nats.request subject
223 |       raise "Did not receive a response from the endpoint"
224 |     end
225 | 
226 |     response.headers["Nats-Service-Error"].should eq "oops"
227 |     response.headers["Nats-Service-Error-Code"].should eq "555"
228 |   end
229 | 
230 |   it "allows concurrent requests to the same endpoint" do
231 |     name = "test-concurrent-requests-#{UUID.v7}"
232 |     svc = nats.services.add name,
233 |       version: "0.1.0",
234 |       description: "does a thing"
235 |     subject = "#{name}.call"
236 |     endpoint = svc.add_endpoint "lol", subject: subject, concurrency: 100 do |request, subscription|
237 |       sleep 10.milliseconds
238 |       nats.reply request, ""
239 |     end
240 | 
241 |     start = Time.monotonic
242 |     WaitGroup.wait do |wg|
243 |       100.times do
244 |         wg.spawn do
245 |           unless response = nats.request subject
246 |             raise "Did not receive a response from the endpoint"
247 |           end
248 |         end
249 |       end
250 |     end
251 |     (Time.monotonic - start).should be_within 10.milliseconds, of: 10.milliseconds
252 |   end
253 | end
254 | 


--------------------------------------------------------------------------------
/src/nkeys.cr:
--------------------------------------------------------------------------------
  1 | require "openssl"
  2 | require "digest"
  3 | require "base32"
  4 | require "./error"
  5 | require "./lib_crypto"
  6 | 
  7 | module NATS
  8 |   private struct NKeys
  9 |     class Error < ::NATS::Error
 10 |     end
 11 | 
 12 |     class InvalidEncoding < Error
 13 |     end
 14 | 
 15 |     class InvalidSeed < Error
 16 |     end
 17 | 
 18 |     class ChecksumFailed < Error
 19 |     end
 20 | 
 21 |     PREFIX_BYTE_SEED = 18 << 3 # B32-encodes to "S..."
 22 | 
 23 |     getter keypair
 24 | 
 25 |     def self.new(string : String)
 26 |       if string.starts_with? "S"
 27 |         new Base32.decode(string)
 28 |       else
 29 |         raise InvalidSeed.new("Must use seed (the key that begins with an 'S' character)")
 30 |       end
 31 |     end
 32 | 
 33 |     def initialize(@seed : Bytes)
 34 |       @keypair = KeyPair.new(seed)
 35 |     end
 36 | 
 37 |     class KeyPair
 38 |       PUBLIC_KEY_SIZE  = 32
 39 |       PRIVATE_KEY_SIZE = 64
 40 |       SIGNATURE_SIZE   = 64
 41 |       SEED_SIZE        = 32
 42 | 
 43 |       # OpenSSL operations store error data in thread-local variables, so we
 44 |       # need to wrap a mutex around them so that two simultaneous errors don't
 45 |       # end up showing the same error to both.
 46 |       MUTEX = Mutex.new
 47 | 
 48 |       private VALID_PUBLIC_PREFIX_BYTES = Set(UInt8){
 49 |         (15 << 3).to_u8, # B32-encodes to "P...", signifies a NATS private key
 50 |         (13 << 3).to_u8, # B32-encodes to "N...", signifies a NATS server
 51 |         (2 << 3).to_u8,  # B32-encodes to "C...", signifies a NATS cluster
 52 |         (14 << 3).to_u8, # B32-encodes to "O...", signifies a NATS operator
 53 |         (0).to_u8,       # B32-encodes to "A...", signifies a NATS account
 54 |         (20 << 3).to_u8, # B32-encodes to "U...", signifies a NATS user
 55 |       }
 56 | 
 57 |       def valid_public_prefix_byte?(byte : UInt8) : Bool
 58 |         VALID_PUBLIC_PREFIX_BYTES.includes? byte
 59 |       end
 60 | 
 61 |       @prefix : UInt8
 62 |       @private_key : Bytes
 63 | 
 64 |       def initialize(@seed : Bytes)
 65 |         raw = seed[0...-2]
 66 |         b1 = raw[0] & 0b11111000
 67 |         b2 = (raw[0] & 0b00000111) << 5 | ((raw[1] & 0b11111000) >> 3)
 68 | 
 69 |         if b1 != PREFIX_BYTE_SEED
 70 |           raise Error.new("Invalid seed: #{Base32.encode(seed)}")
 71 |         elsif !valid_public_prefix_byte?(b2)
 72 |           raise Error.new("Invalid prefix byte: 0x#{b2.to_s(16)}")
 73 |         end
 74 | 
 75 |         prefix = b2
 76 |         result = raw[2..]
 77 |         @prefix = prefix
 78 |         @private_key = result
 79 | 
 80 |         if @private_key.size != SEED_SIZE
 81 |           raise Error.new("Invalid private key size: #{@private_key.size}")
 82 |         end
 83 |       end
 84 | 
 85 |       def sign(string : String | Bytes) : Bytes
 86 |         signature = Bytes.new(SIGNATURE_SIZE)
 87 |         generate_key do |key|
 88 |           md_context = LibCrypto.evp_md_ctx_new
 89 | 
 90 |           MUTEX.synchronize do
 91 |             handle_error if md_context.null?
 92 | 
 93 |             result = LibCrypto.evp_digest_sign_init md_context,
 94 |               out pkey_context,
 95 |               type: Pointer(Void).null,
 96 |               engine: Pointer(LibCrypto::Engine).null,
 97 |               pkey: key
 98 |             handle_error if result == 0
 99 | 
100 |             result = LibCrypto.evp_digest_sign md_context,
101 |               signature.to_unsafe, out siglen,
102 |               string.to_unsafe, string.bytesize
103 |             handle_error if result == 0
104 | 
105 |             signature
106 |           ensure
107 |             LibCrypto.evp_md_ctx_free md_context
108 |           end
109 |         end
110 |       end
111 | 
112 |       def public_key
113 |         bytes = Bytes.new(PUBLIC_KEY_SIZE)
114 |         generate_key do |key|
115 |           MUTEX.synchronize do
116 |             # FIXME: this is heavy-handed, but I think there is something
117 |             # downstream from the evp_digest_sign_init function that prepares
118 |             # the key for the evp_pkey_get_raw_public_key function below. I
119 |             # haven't figured out what it is yet, so I'm just using this for now
120 |             # because it works.
121 |             md_context = LibCrypto.evp_md_ctx_new
122 |             handle_error if md_context.null?
123 |             begin
124 |               result = LibCrypto.evp_digest_sign_init md_context,
125 |                 out pkey_context,
126 |                 type: Pointer(Void).null,
127 |                 engine: Pointer(LibCrypto::Engine).null,
128 |                 pkey: key
129 |             ensure
130 |               LibCrypto.evp_md_ctx_free md_context
131 |             end
132 | 
133 |             result = LibCrypto.evp_pkey_get_raw_public_key(key, bytes.to_unsafe, out len)
134 |             handle_error if result == 0
135 |             if len != PUBLIC_KEY_SIZE
136 |               raise Error.new("Invalid public key size. Expected: #{PUBLIC_KEY_SIZE}, got: #{len}")
137 |             end
138 |           end
139 |         end
140 | 
141 |         io = IO::Memory.new
142 |         io.write_byte key_prefix
143 |         io.write bytes
144 | 
145 |         crc = CRC16.checksum(io.to_slice)
146 |         io.write_bytes crc, IO::ByteFormat::LittleEndian
147 |         io.to_slice
148 |       end
149 | 
150 |       private def key_prefix
151 |         raw = @seed
152 | 
153 |         b1 = raw[0] & 0b11111000
154 |         b2 = (raw[0] & 0b00000111) << 5 | ((raw[1] & 0b11111000) >> 3)
155 | 
156 |         # Does this check need to happen? We check for a valid seed on instantiation
157 |         if b1 != PREFIX_BYTE_SEED
158 |           raise InvalidSeed.new("Prefix byte is invalid")
159 |         end
160 | 
161 |         b2
162 |       end
163 | 
164 |       private def generate_key(&)
165 |         key = LibCrypto.evp_pkey_new_raw_private_key(
166 |           type: LibCrypto::PKEY::ED25519,
167 |           engine: Pointer(LibCrypto::Engine).null,
168 |           key: @private_key.to_unsafe,
169 |           keylen: @private_key.bytesize,
170 |         )
171 | 
172 |         begin
173 |           yield key
174 |         ensure
175 |           LibCrypto.evp_pkey_free key
176 |         end
177 |       end
178 | 
179 |       private macro handle_error
180 |         %error_code = LibCrypto.err_get_error
181 |         %bytes = Bytes.new(256)
182 |         LibCrypto.err_error_string_n(%error_code, %bytes.to_unsafe, 256)
183 |         raise Error.new(String.new(%bytes))
184 |       end
185 |     end
186 | 
187 |     private module CRC16
188 |       extend self
189 | 
190 |       TABLE = {
191 |         0x0000, 0x1021, 0x2042, 0x3063, 0x4084, 0x50a5, 0x60c6, 0x70e7,
192 |         0x8108, 0x9129, 0xa14a, 0xb16b, 0xc18c, 0xd1ad, 0xe1ce, 0xf1ef,
193 |         0x1231, 0x0210, 0x3273, 0x2252, 0x52b5, 0x4294, 0x72f7, 0x62d6,
194 |         0x9339, 0x8318, 0xb37b, 0xa35a, 0xd3bd, 0xc39c, 0xf3ff, 0xe3de,
195 |         0x2462, 0x3443, 0x0420, 0x1401, 0x64e6, 0x74c7, 0x44a4, 0x5485,
196 |         0xa56a, 0xb54b, 0x8528, 0x9509, 0xe5ee, 0xf5cf, 0xc5ac, 0xd58d,
197 |         0x3653, 0x2672, 0x1611, 0x0630, 0x76d7, 0x66f6, 0x5695, 0x46b4,
198 |         0xb75b, 0xa77a, 0x9719, 0x8738, 0xf7df, 0xe7fe, 0xd79d, 0xc7bc,
199 |         0x48c4, 0x58e5, 0x6886, 0x78a7, 0x0840, 0x1861, 0x2802, 0x3823,
200 |         0xc9cc, 0xd9ed, 0xe98e, 0xf9af, 0x8948, 0x9969, 0xa90a, 0xb92b,
201 |         0x5af5, 0x4ad4, 0x7ab7, 0x6a96, 0x1a71, 0x0a50, 0x3a33, 0x2a12,
202 |         0xdbfd, 0xcbdc, 0xfbbf, 0xeb9e, 0x9b79, 0x8b58, 0xbb3b, 0xab1a,
203 |         0x6ca6, 0x7c87, 0x4ce4, 0x5cc5, 0x2c22, 0x3c03, 0x0c60, 0x1c41,
204 |         0xedae, 0xfd8f, 0xcdec, 0xddcd, 0xad2a, 0xbd0b, 0x8d68, 0x9d49,
205 |         0x7e97, 0x6eb6, 0x5ed5, 0x4ef4, 0x3e13, 0x2e32, 0x1e51, 0x0e70,
206 |         0xff9f, 0xefbe, 0xdfdd, 0xcffc, 0xbf1b, 0xaf3a, 0x9f59, 0x8f78,
207 |         0x9188, 0x81a9, 0xb1ca, 0xa1eb, 0xd10c, 0xc12d, 0xf14e, 0xe16f,
208 |         0x1080, 0x00a1, 0x30c2, 0x20e3, 0x5004, 0x4025, 0x7046, 0x6067,
209 |         0x83b9, 0x9398, 0xa3fb, 0xb3da, 0xc33d, 0xd31c, 0xe37f, 0xf35e,
210 |         0x02b1, 0x1290, 0x22f3, 0x32d2, 0x4235, 0x5214, 0x6277, 0x7256,
211 |         0xb5ea, 0xa5cb, 0x95a8, 0x8589, 0xf56e, 0xe54f, 0xd52c, 0xc50d,
212 |         0x34e2, 0x24c3, 0x14a0, 0x0481, 0x7466, 0x6447, 0x5424, 0x4405,
213 |         0xa7db, 0xb7fa, 0x8799, 0x97b8, 0xe75f, 0xf77e, 0xc71d, 0xd73c,
214 |         0x26d3, 0x36f2, 0x0691, 0x16b0, 0x6657, 0x7676, 0x4615, 0x5634,
215 |         0xd94c, 0xc96d, 0xf90e, 0xe92f, 0x99c8, 0x89e9, 0xb98a, 0xa9ab,
216 |         0x5844, 0x4865, 0x7806, 0x6827, 0x18c0, 0x08e1, 0x3882, 0x28a3,
217 |         0xcb7d, 0xdb5c, 0xeb3f, 0xfb1e, 0x8bf9, 0x9bd8, 0xabbb, 0xbb9a,
218 |         0x4a75, 0x5a54, 0x6a37, 0x7a16, 0x0af1, 0x1ad0, 0x2ab3, 0x3a92,
219 |         0xfd2e, 0xed0f, 0xdd6c, 0xcd4d, 0xbdaa, 0xad8b, 0x9de8, 0x8dc9,
220 |         0x7c26, 0x6c07, 0x5c64, 0x4c45, 0x3ca2, 0x2c83, 0x1ce0, 0x0cc1,
221 |         0xef1f, 0xff3e, 0xcf5d, 0xdf7c, 0xaf9b, 0xbfba, 0x8fd9, 0x9ff8,
222 |         0x6e17, 0x7e36, 0x4e55, 0x5e74, 0x2e93, 0x3eb2, 0x0ed1, 0x1ef0,
223 |       }
224 | 
225 |       def checksum(key : Bytes)
226 |         crc = 0u16
227 |         key.each do |byte|
228 |           crc = (crc << 8) ^ TABLE[((crc >> 8) ^ byte) & 0xFF]
229 |         end
230 | 
231 |         crc
232 |       end
233 |     end
234 |   end
235 | end
236 | 


--------------------------------------------------------------------------------
/src/jetstream/streams.cr:
--------------------------------------------------------------------------------
  1 | require "json"
  2 | 
  3 | require "../nats"
  4 | require "./stream"
  5 | require "./stream_config"
  6 | require "./stream_list_response"
  7 | require "./stream_get_msg_response"
  8 | require "./error_response"
  9 | 
 10 | module NATS::JetStream
 11 |   # A stream in NATS JetStream represents the history of messages
 12 |   # pertaining to a given domain. When you publish a message to a subject
 13 |   # that a stream is monitoring, the stream then adds that message to its
 14 |   # history in the order it was published.
 15 |   struct Streams
 16 |     def initialize(@nats : ::NATS::Client)
 17 |     end
 18 | 
 19 |     # Create a stream of the given storage type and with the given
 20 |     # properties, which are passed unmodified to
 21 |     # `NATS::JetStream::StreamConfig.new`.
 22 |     def create(
 23 |       storage : StreamConfig::Storage,
 24 |       retention : StreamConfig::RetentionPolicy? = nil,
 25 |       discard : StreamConfig::DiscardPolicy? = nil,
 26 |       compression : StreamConfig::Compression = :none,
 27 |       **kwargs,
 28 |     ) : Stream
 29 |       create_stream = StreamConfig.new(
 30 |         **kwargs,
 31 |         storage: storage,
 32 |         retention: retention,
 33 |         discard: discard,
 34 |         compression: compression,
 35 |       )
 36 | 
 37 |       if create_stream.name.includes? '.'
 38 |         raise Error.new("Cannot create stream with '.' in the name")
 39 |       end
 40 | 
 41 |       if response = @nats.request "$JS.API.STREAM.CREATE.#{create_stream.name}", create_stream.to_json
 42 |         case parsed = (Stream | ErrorResponse).from_json String.new(response.body)
 43 |         in ErrorResponse
 44 |           raise Error.new("#{parsed.error.description} (#{parsed.error.code})")
 45 |         in Stream
 46 |           parsed
 47 |         end
 48 |       else
 49 |         raise Error.new("Did not receive a response from NATS JetStream")
 50 |       end
 51 |     rescue ex
 52 |       raise ex
 53 |     end
 54 | 
 55 |     # List all available streams
 56 |     def list(subject : String? = nil, offset : Int? = nil, limit : Int? = nil)
 57 |       body = ListRequest.new(subject: subject, offset: offset, limit: limit).to_json
 58 | 
 59 |       if response = @nats.request "$JS.API.STREAM.LIST", body
 60 |         StreamListResponse.new @nats.jetstream,
 61 |           json: JSON::PullParser.new(String.new(response.body)),
 62 |           subject: subject
 63 |       else
 64 |         raise Error.new("Did not receive a response from NATS JetStream")
 65 |       end
 66 |     end
 67 | 
 68 |     private struct ListRequest
 69 |       include JSON::Serializable
 70 |       getter subject : String?
 71 |       getter offset : Int64?
 72 |       getter limit : Int32?
 73 | 
 74 |       def initialize(@subject, offset, limit)
 75 |         @offset = offset.to_i64 if offset
 76 |         @limit = limit.to_i32 if limit
 77 |       end
 78 |     end
 79 | 
 80 |     # Get the current state of the stream with the given `name`
 81 |     def info(name : String) : Stream?
 82 |       if response = @nats.request "$JS.API.STREAM.INFO.#{name}"
 83 |         case parsed = (Stream | ErrorResponse).from_json(String.new(response.body))
 84 |         in Stream
 85 |           parsed
 86 |         in ErrorResponse
 87 |           if parsed.error.err_code.stream_not_found?
 88 |             nil
 89 |           else
 90 |             raise Error.new(parsed.error.description)
 91 |           end
 92 |         end
 93 |       else
 94 |         raise Error.new("Response timed out while fetching stream #{name.inspect}")
 95 |       end
 96 |     end
 97 | 
 98 |     # Delete the given stream
 99 |     def delete(stream : JetStream::Stream)
100 |       delete stream.config.name
101 |     end
102 | 
103 |     # Delete the stream with the given name
104 |     def delete(stream : String)
105 |       @nats.request "$JS.API.STREAM.DELETE.#{stream}"
106 |     end
107 | 
108 |     def get_msg(stream : String, *, last_by_subject : String)
109 |       get_msg stream, {last_by_subj: last_by_subject}
110 |     end
111 | 
112 |     def get_msg(stream : String, *, sequence : Int, next_by_subject : String? = nil)
113 |       get_msg stream, {seq: sequence, next_by_subj: next_by_subject}
114 |     end
115 | 
116 |     protected def get_msg(stream : String, params)
117 |       if response = @nats.request "$JS.API.STREAM.MSG.GET.#{stream}", params.to_json
118 |         case parsed = (StreamGetMsgResponse | ErrorResponse).from_json String.new(response.body)
119 |         in StreamGetMsgResponse
120 |           parsed
121 |         in ErrorResponse
122 |           if parsed.error.err_code.no_message_found?
123 |             nil # No message
124 |           else
125 |             raise Error.new(parsed.error.description)
126 |           end
127 |         end
128 |       else
129 |         raise Error.new("Did not receive a response when getting message from stream #{stream.inspect} with options #{params}")
130 |       end
131 |     end
132 | 
133 |     # The `get_msg` API involves some administrative overhead and usually routes
134 |     # to the stream's primary node in the NATS cluster. The `direct_get` method
135 |     # uses the `DIRECT.GET` API which allows any server hosting the stream
136 |     # (including replicas) to respond with the message data. Specifying
137 |     # `last_by_subject` allows you to get the last message in a stream that was
138 |     # published to a specific subject. This is used by `NATS::KV` internally to
139 |     # fetch values for a given key from replicas for the KV's backing stream.
140 |     #
141 |     # NOTE: In order to use this API, the stream _must_ have been created with
142 |     # [`allow_direct`](https://jgaskins.dev/nats/NATS/JetStream/StreamConfig.html#allow_direct%3F%3ABool%7CNil-instance-method)
143 |     # set to `true`. For performance reasons, the client does not perform this
144 |     # check.
145 |     def direct_get(stream : String, *, last_by_subject : String) : JetStream::StreamGetMsgResponse?
146 |       direct_get stream, {last_by_subj: last_by_subject}
147 |     end
148 | 
149 |     # The `get_msg` API involves some administrative overhead and usually routes
150 |     # to the stream's primary node in the NATS cluster. The `direct_get` method
151 |     # uses the `DIRECT.GET` API which allows any server hosting the stream
152 |     # (including replicas) to respond with the message data. Specifying
153 |     # `last_by_subject` allows you to get the last message in a stream that was
154 |     # published to a specific subject. This is used by `NATS::KV` internally to
155 |     # fetch values for a given key from replicas for the KV's backing stream.
156 |     #
157 |     # NOTE: In order to use this API, the stream _must_ have been created with
158 |     # [`allow_direct`](https://jgaskins.dev/nats/NATS/JetStream/StreamConfig.html#allow_direct%3F%3ABool%7CNil-instance-method)
159 |     # set to `true`. For performance reasons, the client does not perform this
160 |     # check.
161 |     def direct_get(stream : String, *, sequence : Int, next_by_subject : String? = nil)
162 |       direct_get stream, {seq: sequence, next_by_subj: next_by_subject}
163 |     end
164 | 
165 |     protected def direct_get(stream : String, params) : JetStream::StreamGetMsgResponse?
166 |       if response = @nats.request "$JS.API.DIRECT.GET.#{stream}", params.to_json
167 |         if headers = response.headers
168 |           return nil if headers["Status"]?.try(&.starts_with?("404"))
169 |           StreamGetMsgResponse.new(
170 |             message: StreamGetMsgResponse::Message.new(
171 |               subject: headers["Nats-Subject"],
172 |               seq: headers["Nats-Sequence"].to_i64,
173 |               data_string: response.data_string,
174 |               headers: headers,
175 |               time: Time::Format::RFC_3339.parse(headers["Nats-Time-Stamp"]),
176 |             ),
177 |           )
178 |         else
179 |           raise Error.new("Unexpected response to NATS::JetStream::Streams#direct_get (missing headers) - #{response.inspect}")
180 |         end
181 | 
182 |         # case parsed = (StreamGetMsgResponse | ErrorResponse).from_json String.new(response.body)
183 |         # in StreamGetMsgResponse
184 |         #   parsed
185 |         # in ErrorResponse
186 |         #   if parsed.error.err_code.no_message_found?
187 |         #     nil # No message
188 |         #   else
189 |         #     raise Error.new(parsed.error.description)
190 |         #   end
191 |         # end
192 |       else
193 |         raise Error.new("Did not receive a response when getting message from stream #{stream.inspect} with options #{params}")
194 |       end
195 |     end
196 | 
197 |     def purge(stream : String, subject : String) : Int64
198 |       if response = @nats.request("$JS.API.STREAM.PURGE.#{stream}", {filter: subject}.to_json)
199 |         case parsed = (PurgeStreamResponse | ErrorResponse).from_json String.new(response.body)
200 |         in PurgeStreamResponse
201 |           parsed.purged
202 |         in ErrorResponse
203 |           raise Error.new(parsed.error.description)
204 |         end
205 |       else
206 |         raise Error.new("Did not receive a response when purging stream #{stream.inspect} of subject #{subject.inspect}")
207 |       end
208 |     end
209 | 
210 |     struct PurgeStreamResponse
211 |       include JSON::Serializable
212 | 
213 |       getter purged : Int64
214 |     end
215 |   end
216 | 
217 |   deprecate_api_v1 Streams
218 | end
219 | 


--------------------------------------------------------------------------------
/spec/kv_spec.cr:
--------------------------------------------------------------------------------
  1 | require "./spec_helper"
  2 | 
  3 | require "../src/kv"
  4 | require "uuid"
  5 | 
  6 | private def test(name, bucket_options = {history: 10}, **options, &block : NATS::KV::Bucket, String ->)
  7 |   it name, **options do
  8 |     name = UUID.random.to_s
  9 |     bucket = kv.create_bucket(name, **bucket_options)
 10 | 
 11 |     begin
 12 |       block.call bucket, name
 13 |     ensure
 14 |       kv.delete bucket
 15 |     end
 16 |   end
 17 | end
 18 | 
 19 | private NATS_CLIENT = NATS::Client.new
 20 | 
 21 | private def nats
 22 |   NATS_CLIENT
 23 | end
 24 | 
 25 | def kv
 26 |   nats.kv
 27 | end
 28 | 
 29 | describe NATS::KV do
 30 |   if ENV["CLEAN_OUT_BUCKETS"]? == "true"
 31 |     nats.jetstream.stream.list.each do |stream|
 32 |       if stream.config.name =~ /\AKV_[[:xdigit:]]{8}-([[:xdigit:]]{4}-){3}[[:xdigit:]]{12}\z/
 33 |         nats.jetstream.stream.delete stream
 34 |       end
 35 |     end
 36 |   end
 37 | 
 38 |   it "creates and deletes buckets (streams prefixed with `KV_`)" do
 39 |     name = UUID.random.to_s
 40 |     bucket = kv.create_bucket(name)
 41 |     bucket.name.should eq name
 42 |     kv.get_bucket(name).not_nil!.name.should eq name
 43 |     kv.get_bucket(name).should be_a NATS::KV::Bucket
 44 | 
 45 |     kv.delete_bucket name
 46 |     kv.get_bucket(name).should eq nil
 47 |   end
 48 | 
 49 |   test "lists buckets" do |bucket, name|
 50 |     bucket["one"] = "1"
 51 |     bucket["two"] = "2"
 52 | 
 53 |     buckets = kv.list_buckets(pattern: name)
 54 | 
 55 |     buckets.total.should eq 1
 56 |     buckets.limit.should eq 256
 57 |     buckets.offset.should eq 0
 58 |     buckets.first.name.should eq name
 59 |     buckets.first.values.should eq 2
 60 |   end
 61 | 
 62 |   test "sets values" do |bucket, name|
 63 |     bucket.put "key", "value"
 64 | 
 65 |     if result = bucket.get("key")
 66 |       result.revision.should eq 1
 67 |       result.key.should eq "key"
 68 |       result.value.should eq "value".to_slice
 69 |       result.operation.put?.should eq true
 70 |       result.bucket.should eq name
 71 |     else
 72 |       raise "Could not fetch key from bucket, result was `nil`"
 73 |     end
 74 |   end
 75 | 
 76 |   test "sets values with a TTL", bucket_options: {allow_msg_ttl: true} do |bucket, name|
 77 |     # We create a lot of values with TTLs to mitigate false positive & negatives
 78 |     # due to sending/checking them at just the right time. I hate flaky tests.
 79 |     concurrency = 10_000
 80 |     channel = Channel(Exception?).new(concurrency)
 81 |     concurrency.times do |i|
 82 |       spawn do
 83 |         key = "key-#{i}"
 84 |         bucket.put key, "value", ttl: 1.second
 85 |         bucket.get(key).should_not eq nil
 86 |         sleep 2.second # per-message TTLs apparently have 1-second precision 😞
 87 |         bucket.get(key).should eq nil
 88 |       rescue ex
 89 |         error = ex
 90 |       ensure
 91 |         channel.send error
 92 |       end
 93 |     end
 94 | 
 95 |     concurrency.times do
 96 |       if error = channel.receive
 97 |         raise error
 98 |       end
 99 |     end
100 |   end
101 | 
102 |   test "gets a specific revision of a key" do |bucket, name|
103 |     bucket.put "key", "value1"
104 |     bucket.put "key", "value2"
105 |     revision = bucket.put "another-key", "another value"
106 |     bucket.put "key", "value3"
107 |     bucket.put "key", "value4"
108 | 
109 |     bucket.get!("key", revision: revision).value.should eq "value3".to_slice
110 |   end
111 | 
112 |   test "creates a key or returns nil if the key already exists" do |bucket, name|
113 |     # Passes the first time because the key does not exist. Also, since this is
114 |     # the first key being added to this store (see `test` macro above), the
115 |     # revision is guaranteed to be `1`.
116 |     bucket.create("key", "value").should eq 1
117 | 
118 |     # Fails the second time because the key already exists
119 |     bucket.create("key", "value").should eq nil
120 |   end
121 | 
122 |   describe "updating a key" do
123 |     test "updates a key if the revision matches" do |bucket, name|
124 |       if revision = bucket.create "key", "value"
125 |         bucket.update("key", "value2", revision).should eq 2
126 |         bucket.get!("key").value.should eq "value2".to_slice
127 |       else
128 |         raise "No revision returned from Bucket#create"
129 |       end
130 |     end
131 | 
132 |     test "does not update a key if the revision does not match" do |bucket, name|
133 |       if revision = bucket.create "key", "value"
134 |         bucket.put "key", "value2"
135 |         bucket.update("key", "value3", revision).should eq nil
136 |         bucket["key"]?.should eq "value2".to_slice
137 |       else
138 |         raise "No revision returned from Bucket#create"
139 |       end
140 |     end
141 | 
142 |     test "does not update a key if history is exceeded and discard_new_per_key is set", bucket_options: {history: 2, discard_new_per_key: true} do |bucket, name|
143 |       bucket.put "a", "1"
144 |       bucket.put "a", "2"
145 | 
146 |       expect_raises NATS::KV::Error, "maximum messages per subject exceeded" do
147 |         bucket.put("a", "3")
148 |       end
149 |     end
150 | 
151 |     test "updates a key if another key is updated since the last time the given key was set" do |bucket, name|
152 |       bucket.put "key", "value"
153 |       bucket.put "key2", "value2"
154 | 
155 |       # The revision is scoped to the bucket rather than to the key, so since
156 |       # this is the third modification we've made to keys in this bucket, this
157 |       # revision is #3.
158 |       bucket.update("key", "value3", revision: 1).should eq 3
159 | 
160 |       bucket["key"]?.should eq "value3".to_slice
161 |     end
162 |   end
163 | 
164 |   describe "getting a key" do
165 |     test "a key that does not exist at all returns nil" do |bucket, name|
166 |       bucket.get("lol").should eq nil
167 |     end
168 | 
169 |     test "a key that does exist will return a KV::Entry for that key" do |bucket, name|
170 |       bucket.put "key", "value"
171 | 
172 |       result = bucket.get("key").not_nil!
173 | 
174 |       result.value.should eq "value".to_slice
175 |     end
176 | 
177 |     test "a key that has been deleted will return a KV::Entry whose `operation` is a `Delete`" do |bucket, name|
178 |       bucket.put "deleted", "value"
179 |       bucket.delete "deleted"
180 | 
181 |       result = bucket.get("deleted").not_nil!
182 | 
183 |       result.value.should be_empty
184 |       result.operation.delete?.should eq true
185 |     end
186 | 
187 |     test "a key that has been deleted can return `nil` if you ignore deleted" do |bucket, name|
188 |       bucket.put "deleted", "value"
189 |       bucket.delete "deleted"
190 | 
191 |       result = bucket.get("deleted", ignore_deletes: true)
192 | 
193 |       result.should be_nil
194 |     end
195 | 
196 |     test "a key that is purged will show the purge item" do |bucket, name|
197 |       bucket.put "purged", "value"
198 |       bucket.purge "purged"
199 | 
200 |       result = bucket.get("purged").not_nil!
201 | 
202 |       result.operation.purge?.should eq true
203 |     end
204 |   end
205 | 
206 |   describe "listing keys" do
207 |     test "lists keys from Put operations" do |bucket, name|
208 |       bucket.put "a", "a"
209 |       bucket.put "b", "b"
210 | 
211 |       bucket.keys.should contain "a"
212 |       bucket.keys.should contain "b"
213 |     end
214 | 
215 |     test "returns an empty set when there are no keys" do |bucket, name|
216 |       bucket.keys.should be_empty
217 |     end
218 | 
219 |     test "ignores keys that are deleted or purged" do |bucket, name|
220 |       bucket.put "a", "a"
221 |       bucket.put "b", "b"
222 |       bucket.put "deleted", "lol"
223 |       bucket.put "purged", "omg"
224 | 
225 |       bucket.delete "deleted"
226 |       bucket.purge "purged"
227 | 
228 |       bucket.keys.should contain "a"
229 |       bucket.keys.should contain "b"
230 |       bucket.keys.should_not contain "deleted"
231 |       bucket.keys.should_not contain "purged"
232 |     end
233 | 
234 |     test "iterates over keys, ignoring history and deleted keys" do |bucket, name|
235 |       bucket["deleted"] = "delete me now plz"
236 |       bucket.delete "deleted"
237 |       bucket["a"] = "a"
238 |       bucket["b"] = "b"
239 |       bucket["purged"] = "purge me"
240 |       bucket.purge "purged"
241 | 
242 |       bucket.each_key do |key|
243 |         %w[a b].should contain key
244 |       end
245 |     end
246 | 
247 |     test "iterates over keys with a specific pattern" do |bucket|
248 |       bucket["included.1"] = "1"
249 |       bucket["included.2"] = "2"
250 |       bucket["excluded.1"] = "nope"
251 | 
252 |       count = 0
253 |       bucket.each_key pattern: "included.*" do |key|
254 |         count += 1
255 |         key.should start_with "included."
256 |       end
257 |       count.should eq 2
258 | 
259 |       count = 0
260 |       bucket.each_key pattern: "*.1" do |key|
261 |         count += 1
262 |         key.should end_with ".1"
263 |       end
264 |       count.should eq 2
265 |     end
266 |   end
267 | 
268 |   describe "getting the history of a key" do
269 |     test "it gets the full history of the key in chronological order" do |bucket, name|
270 |       key = "key"
271 |       10.times do |i|
272 |         bucket[key] = i.to_s
273 |       end
274 | 
275 |       bucket.history(key).map(&.value).should eq Array.new(10, &.to_s.to_slice)
276 |     end
277 | 
278 |     test "it returns an empty array if there is no history" do |bucket, name|
279 |       bucket.history("my-key").should be_empty
280 |     end
281 |   end
282 | end
283 | 


--------------------------------------------------------------------------------
/src/jetstream/client.cr:
--------------------------------------------------------------------------------
  1 | require "../nats"
  2 | require "./streams"
  3 | require "./consumers"
  4 | require "./nak_backoff"
  5 | require "./pub_ack"
  6 | require "./pull_subscription"
  7 | 
  8 | module NATS::JetStream
  9 |   # This class provides a client for NATS JetStream for at-least-once delivery.
 10 |   # You can either instantiate it with a NATS client or with the
 11 |   # `NATS::Client#jetstream` method as a shortcut.
 12 |   class Client
 13 |     def initialize(@nats : ::NATS::Client)
 14 |     end
 15 | 
 16 |     # Returns an `API::Stream` instance to interact with the NATS JetStream
 17 |     # API for streams.
 18 |     def stream
 19 |       Streams.new(@nats)
 20 |     end
 21 | 
 22 |     # Returns an `API::Consumer` instance to interact with the NATS JetStream
 23 |     # API for consumers.
 24 |     def consumer
 25 |       Consumers.new(@nats)
 26 |     end
 27 | 
 28 |     def publish(
 29 |       subject : String,
 30 |       body : Data,
 31 |       timeout : Time::Span = 2.seconds,
 32 |       headers : Headers = Headers.new,
 33 |       message_id : String? = nil,
 34 |       expected_last_message_id : String? = nil,
 35 |       expected_last_sequence : Int64? = nil,
 36 |       expected_stream : String? = nil,
 37 |       expected_last_subject_sequence : Int64? = nil,
 38 |     )
 39 |       headers["Nats-Msg-Id"] = message_id if message_id
 40 |       headers["Nats-Expected-Last-Msg-Id"] = expected_last_message_id if expected_last_message_id
 41 |       headers["Nats-Expected-Stream"] = expected_stream if expected_stream
 42 |       headers["Nats-Expected-Last-Sequence"] = expected_last_sequence if expected_last_sequence
 43 |       headers["Nats-Expected-Last-Subject-Sequence"] = expected_last_subject_sequence.to_s if expected_last_subject_sequence
 44 | 
 45 |       if response = @nats.request(subject, body, timeout: timeout, headers: headers)
 46 |         (PubAck | ErrorResponse).from_json(String.new(response.body))
 47 |       end
 48 |     end
 49 | 
 50 |     # Subscribe to messages delivered to the given consumer. Note that this
 51 |     # consumer _must_ be a push-based consumer. Pull-based consumers do not
 52 |     # allow subscriptions because you must explicitly request the next
 53 |     # message.
 54 |     #
 55 |     # ```
 56 |     # js = nats.jetstream
 57 |     # consumer = js.consumer.info("orders", "fulfillment")
 58 |     # js.subscribe consumer do |msg|
 59 |     #   # ...
 60 |     #
 61 |     #   js.ack msg
 62 |     # end
 63 |     # ```
 64 |     def subscribe(consumer : JetStream::Consumer, concurrency : Int = 1, &block : Message, Subscription ->)
 65 |       if subject = consumer.config.deliver_subject
 66 |         subscribe subject,
 67 |           queue_group: consumer.config.deliver_group,
 68 |           concurrency: concurrency,
 69 |           &block
 70 |       else
 71 |         raise ArgumentError.new("Consumer is not a push consumer (no `deliver_subject`)")
 72 |       end
 73 |     end
 74 | 
 75 |     # Subscribe to the given subject with an optional queue group. This is
 76 |     # effectively identical to `NATS::Client#subscribe`, but the message
 77 |     # yielded to the block is a `NATS::JetStream::Message` instead of
 78 |     # a `NATS::Message`.
 79 |     #
 80 |     # ```
 81 |     # js = nats.jetstream
 82 |     # js.subscribe "orders.*", queue_group: "fulfillment" do |msg|
 83 |     #   # ...
 84 |     #
 85 |     #   js.ack msg
 86 |     # end
 87 |     # ```
 88 |     #
 89 |     # _NOTE:_ If provided, the `queue_group` _must_ be the same as a `Consumer`'s `deliver_group` for NATS server 2.4.0 and above.
 90 |     def subscribe(subject : String, queue_group : String? = nil, concurrency : Int = 1, &block : Message, Subscription ->)
 91 |       @nats.subscribe subject, queue_group: queue_group, concurrency: concurrency do |msg, subscription|
 92 |         unless (headers = msg.headers) && headers["Status"]? == "100 Idle Heartbeat"
 93 |           block.call Message.new(msg), subscription
 94 |         end
 95 |       end
 96 |     end
 97 | 
 98 |     @[Experimental("NATS JetStream pull subscriptions may be unstable")]
 99 |     def pull_each(consumer : Consumer, *, batch_size : Int, &) : Nil
100 |       pull_subscribe consumer, batch_size: batch_size do |msgs, pull|
101 |         msgs.each { |msg| yield msg, pull }
102 |       end
103 |     end
104 | 
105 |     @[Experimental("NATS JetStream pull subscriptions may be unstable")]
106 |     def pull_subscribe(consumer : Consumer, *, batch_size : Int, &) : Nil
107 |       pull = pull_subscribe(consumer, backlog: batch_size)
108 |       until pull.closed?
109 |         yield pull.fetch(batch_size), pull
110 |       end
111 |     end
112 | 
113 |     @[Experimental("NATS JetStream pull subscriptions may be unstable")]
114 |     def pull_subscribe(consumer : Consumer, backlog : Int = 64)
115 |       if consumer.config.deliver_subject
116 |         raise ArgumentError.new("Cannot set up a pull-based subscription to a push-based consumer: #{consumer.name.inspect} on stream #{consumer.stream_name.inspect}")
117 |       end
118 | 
119 |       PullSubscription.new(consumer, @nats)
120 |     end
121 | 
122 |     # Acknowledge success processing the specified message, usually called at
123 |     # the end of your subscription block.
124 |     #
125 |     # NOTE: This method is asynchronous. If you need a guarantee that NATS has
126 |     # received your acknowledgement, use `ack_sync` instead.
127 |     #
128 |     # ```
129 |     # jetstream.subscribe consumer do |msg|
130 |     #   # ...
131 |     #
132 |     #   jetstream.ack msg
133 |     # end
134 |     # ```
135 |     def ack(msg : Message)
136 |       @nats.publish msg.reply_to, "+ACK"
137 |     end
138 | 
139 |     # Acknowledge the given message, waiting on the NATS server to acknowledge
140 |     # your acknowledgement so that you can be sure it was delivered to the
141 |     # server and not simply caught up in the output buffer.
142 |     #
143 |     # ```
144 |     # jetstream.subscribe consumer do |msg|
145 |     #   # ...
146 |     #
147 |     #   jetstream.ack_sync msg
148 |     #   # By the time you get here, the NATS server knows you've acknowledged.
149 |     # end
150 |     # ```
151 |     def ack_sync(msg : Message, timeout : Time::Span = 2.seconds)
152 |       @nats.request msg.reply_to, "+ACK", timeout: timeout
153 |     end
154 | 
155 |     def ack_sync(messages : Enumerable(Message), timeout : Time::Span = 2.seconds)
156 |       channel = Channel(Bool).new(messages.size)
157 |       messages.each do |msg|
158 |         @nats.request msg.reply_to, "+ACK", timeout: timeout do |response|
159 |           channel.send true
160 |         end
161 |       end
162 | 
163 |       count = 0
164 |       messages.each do
165 |         select
166 |         when channel.receive
167 |           count += 1
168 |         when timeout(timeout)
169 |         end
170 |       end
171 |       count
172 |     end
173 | 
174 |     # Notify the NATS server that you need more time to process this message,
175 |     # usually used when a consumer requires that you acknowledge a message
176 |     # within a certain amount of time but a given message is taking longer
177 |     # than expected.
178 |     #
179 |     # ```
180 |     # jetstream.subscribe consumer do |msg|
181 |     #   start = Time.monotonic
182 |     #   users.each do |user|
183 |     #     # If we're running out of time, reset the timer.
184 |     #     if Time.monotonic - start > 25.seconds
185 |     #       jetstream.in_progress msg
186 |     #     end
187 |     #
188 |     #     process(msg)
189 |     #   end
190 |     # end
191 |     # ```
192 |     def in_progress(msg : Message)
193 |       @nats.publish msg.reply_to, "+WPI"
194 |     end
195 | 
196 |     # Negatively acknowledge the processing of a message, typically called
197 |     # when an exception is raised while processing.
198 |     #
199 |     # ```
200 |     # jetstream.subscribe consumer do |msg|
201 |     #   # doing some work
202 |     #
203 |     #   jetstream.ack msg # Successfully processed
204 |     # rescue ex
205 |     #   jetstream.nack msg # Processing was unsuccessful, try again.
206 |     # end
207 |     # ```
208 |     def nack(msg : Message)
209 |       @nats.publish msg.reply_to, "-NAK"
210 |     end
211 | 
212 |     # Deliver a negative acknowledgement for the given message and tell the
213 |     # NATS server to delay sending it based on the `NAKBackoff` pattern
214 |     # specified.
215 |     #
216 |     # ```
217 |     # jetstream.subscribe consumer do |msg|
218 |     #   # do some work
219 |     #   jetstream.ack msg
220 |     # rescue
221 |     #   # Use exponential backoff of up to an hour for retries
222 |     #   jetstream.nack msg, backoff: :exponential, max: 1.hour
223 |     # end
224 |     # ```
225 |     def nack(msg : Message, *, backoff : NAKBackoff, max : Time::Span = 1.day)
226 |       case backoff
227 |       in .exponential?
228 |         delay = {(2.0**(msg.delivered_count - 5)).seconds, max}.min
229 |       in .linear?
230 |         delay = {msg.delivered_count.seconds, max}.min
231 |       end
232 | 
233 |       nack msg, delay: delay
234 |     end
235 | 
236 |     # Deliver a negative acknowledgement for the given message and tell the
237 |     # NATS server to delay sending it for the given time span.
238 |     #
239 |     # ```
240 |     # jetstream.subscribe consumer do |msg|
241 |     #   # do some work
242 |     #   jetstream.ack msg
243 |     # rescue
244 |     #   # Use exponential backoff of up to an hour for retries
245 |     #   jetstream.nack msg, delay: 30.seconds
246 |     # end
247 |     # ```
248 |     def nack(msg : Message, *, delay : Time::Span)
249 |       @nats.publish msg.reply_to, %(-NAK {"delay":#{delay.total_nanoseconds.to_i64}})
250 |     end
251 |   end
252 | end
253 | 


--------------------------------------------------------------------------------
/spec/nats_spec.cr:
--------------------------------------------------------------------------------
  1 | require "./spec_helper"
  2 | require "../src/nats"
  3 | require "uuid"
  4 | require "wait_group"
  5 | 
  6 | nats = NATS::Client.new
  7 | 
  8 | describe NATS do
  9 |   it "can publish and subscribe to messages" do
 10 |     subject = "temp.#{UUID.random}"
 11 |     string = ""
 12 | 
 13 |     nats.subscribe subject do |msg|
 14 |       string = String.new(msg.body)
 15 |     end
 16 | 
 17 |     nats.publish subject, "foo"
 18 |     nats.flush
 19 | 
 20 |     string.should eq "foo"
 21 |   end
 22 | 
 23 |   Hash(Char, String){
 24 |     '\0' => "foo\0",
 25 |     ' '  => "foo bar",
 26 |     '*'  => "foo*",
 27 |     '>'  => "<foo>",
 28 |   }.each do |invalid_char, subject|
 29 |     it "raises ArgumentError if the subject contains #{invalid_char.inspect}" do
 30 |       expect_raises ArgumentError do
 31 |         nats.publish subject, ""
 32 |       end
 33 |     end
 34 |   end
 35 | 
 36 |   it "can set message headers without a reply-to" do
 37 |     subject = "temp.#{UUID.random}"
 38 |     headers = nil
 39 |     body = Bytes.empty
 40 | 
 41 |     nats.subscribe subject do |msg|
 42 |       headers = msg.headers
 43 |       body = msg.body
 44 |     end
 45 | 
 46 |     nats.publish subject, "asdf", headers: NATS::Message::Headers{"foo" => "bar"}
 47 |     nats.flush
 48 | 
 49 |     String.new(body).should eq "asdf"
 50 |     headers.should eq NATS::Message::Headers{"foo" => "bar"}
 51 |   end
 52 | 
 53 |   it "can set multiple of the same message header" do
 54 |     subject = "temp.#{UUID.random}"
 55 |     nats.subscribe subject do |msg|
 56 |       nats.reply msg, "", headers: NATS::Message::Headers{
 57 |         "one"  => "one",
 58 |         "many" => %w[one two],
 59 |       }
 60 |     end
 61 | 
 62 |     unless response = nats.request subject, ""
 63 |       raise "Did not receive a response from the endpoint"
 64 |     end
 65 | 
 66 |     response.headers.should eq NATS::Message::Headers{
 67 |       "one"  => "one",
 68 |       "many" => %w[one two],
 69 |     }
 70 |   end
 71 | 
 72 |   it "treats header keys as case-insensitive" do
 73 |     subject = "temp.#{UUID.random}"
 74 |     nats.subscribe subject do |msg|
 75 |       nats.reply msg, "", headers: NATS::Message::Headers{
 76 |         "CASE" => "insensitive",
 77 |       }
 78 |     end
 79 | 
 80 |     unless response = nats.request subject, ""
 81 |       raise "Did not receive a response from the endpoint"
 82 |     end
 83 | 
 84 |     response.headers.should eq NATS::Message::Headers{
 85 |       "case" => "insensitive",
 86 |     }
 87 |   end
 88 | 
 89 |   it "can set message headers with a reply-to" do
 90 |     subject = "temp.#{UUID.random}"
 91 |     headers = nil
 92 |     body = Bytes.empty
 93 |     reply_to = nil
 94 | 
 95 |     nats.subscribe subject do |msg|
 96 |       headers = msg.headers
 97 |       body = msg.body
 98 |       reply_to = msg.reply_to
 99 |     end
100 | 
101 |     nats.publish subject, "asdf", reply_to: "my-reply-to", headers: NATS::Message::Headers{"foo" => "bar"}
102 |     nats.flush
103 | 
104 |     String.new(body).should eq "asdf"
105 |     reply_to.should eq "my-reply-to"
106 |     headers.should eq NATS::Message::Headers{"foo" => "bar"}
107 |   end
108 | 
109 |   it "can publish to multiple subscribers" do
110 |     subject = "temp.#{UUID.random}"
111 | 
112 |     count = 0
113 |     2.times do
114 |       nats.subscribe(subject) { count += 1 }
115 |     end
116 | 
117 |     nats.publish subject, ""
118 |     nats.flush # Flush the published message
119 | 
120 |     count.should eq 2
121 |   end
122 | 
123 |   it "can unsubscribe from subjects" do
124 |     subject = "temp.#{UUID.random}"
125 |     count = 0
126 | 
127 |     subbed = nats.subscribe(subject) { count += 1 }
128 |     unsubbed = nats.subscribe(subject) { count += 1 }
129 | 
130 |     # We subscribed, now we're gonna unsub from one of them
131 |     nats.unsubscribe unsubbed
132 | 
133 |     nats.publish subject, ""
134 |     nats.flush
135 | 
136 |     # Only one of the two `subscribe` blocks should have run
137 |     count.should eq 1
138 |   end
139 | 
140 |   it "can make requests and reply to those requests" do
141 |     subject = "temp.#{UUID.random}"
142 | 
143 |     nats.subscribe subject do |msg|
144 |       nats.reply msg, String.new(msg.body).upcase
145 |     end
146 | 
147 |     if response = nats.request(subject, "foo")
148 |       response.body.should eq "FOO".to_slice
149 |     else
150 |       raise "No response received"
151 |     end
152 |   end
153 | 
154 |   it "can handle multiple messages on the same subject concurrently" do
155 |     subject = "temp.#{UUID.v7}"
156 |     nats.subscribe subject, concurrency: 100 do |request, subscription|
157 |       sleep 20.milliseconds
158 |       nats.reply request, ""
159 |     end
160 | 
161 |     start = Time.monotonic
162 |     WaitGroup.wait do |wg|
163 |       100.times do
164 |         wg.spawn do
165 |           unless response = nats.request subject
166 |             raise "Did not receive a response from the endpoint"
167 |           end
168 |         end
169 |       end
170 |     end
171 |     (Time.monotonic - start).should be_within 20.milliseconds, of: 20.milliseconds
172 |   end
173 | 
174 |   it "assigns replies to the original requesters" do
175 |     subject = "temp.#{UUID.random}"
176 |     # Echoing requests back to their requesters
177 |     nats.subscribe subject do |msg|
178 |       sleep rand.microseconds
179 |       nats.reply msg, msg.body
180 |     end
181 | 
182 |     channel = Channel(Nil).new
183 |     replies = Array.new(100) { -1 }
184 |     100.times do |i|
185 |       spawn do
186 |         if response = nats.request(subject, i.to_s)
187 |           replies[i] = String.new(response.body).to_i
188 |         end
189 |       ensure
190 |         channel.send nil
191 |       end
192 |     end
193 |     100.times { channel.receive }
194 | 
195 |     replies.should eq Array.new(100, &.itself)
196 |   end
197 | 
198 |   it "receives a reply from only a single subscriber" do
199 |     subject = "temp.#{UUID.random}"
200 | 
201 |     10.times do |i|
202 |       nats.subscribe subject do |msg|
203 |         nats.reply msg, i.to_s
204 |       end
205 |     end
206 | 
207 |     response = nats.request(subject, "") || raise "no response"
208 |     # We have no guarantee which subscriber responds first, so we'll just make
209 |     # sure that *one* of them did.
210 |     (0...10).should contain String.new(response.body).to_i
211 |   end
212 | 
213 |   it "receives a single reply when requested asynchronously with a block" do
214 |     subject = "temp.#{UUID.random}"
215 |     count = 0
216 | 
217 |     10.times do |i|
218 |       nats.subscribe subject do |msg|
219 |         nats.reply msg, i.to_s
220 |       end
221 |     end
222 | 
223 |     nats.request(subject, "") do |response|
224 |       count += 1
225 |     end
226 |     nats.flush              # Send the request
227 |     nats.flush              # Give the response time to come back
228 |     10.times { nats.flush } # Just to see if we're gonna get back any more
229 | 
230 |     count.should eq 1
231 |   end
232 | 
233 |   it "returns early when there are no responders" do
234 |     subject = "temp.#{UUID.random}"
235 |     called = false
236 | 
237 |     start = Time.monotonic
238 |     response = nats.request(subject, "", timeout: 1.second)
239 |     finish = Time.monotonic
240 | 
241 |     called.should eq false
242 |     response.should eq nil
243 |     ((finish - start) < 1.second).should eq true
244 |   end
245 | 
246 |   it "handles disconnects" do
247 |     subject = "temp.#{UUID.random}"
248 |     nats.@socket.close # OOPS WE BROKE THE INTERNET
249 |     data = nil
250 | 
251 |     nats.subscribe subject do |msg|
252 |       data = msg.body
253 |     end
254 |     sleep 100.milliseconds # Allow for reconnect
255 | 
256 |     nats.publish subject, "yep"
257 |     nats.flush
258 | 
259 |     data.should eq "yep".to_slice
260 |   end
261 | 
262 |   it "buffers data after a disconnect and sends it upon reconnection" do
263 |     subject = "temp.#{UUID.random}"
264 |     data = nil
265 | 
266 |     nats.subscribe subject do |msg|
267 |       data = msg.body
268 |     end
269 |     nats.@socket.close     # OOPS WE BROKE THE INTERNET
270 |     sleep 100.milliseconds # Allow time to reconnect
271 | 
272 |     nats.publish subject, "yep"
273 |     nats.flush
274 | 
275 |     data.should eq "yep".to_slice
276 |   end
277 | 
278 |   it "drains subscriptions" do
279 |     n = NATS::Client.new
280 |     begin
281 |       first = UUID.random.to_s
282 |       second = UUID.random.to_s
283 |       msgs = Hash(String, Array(String)).new { |h, k| h[k] = [] of String }
284 |       n.subscribe first do |msg|
285 |         msgs[first] << String.new(msg.body)
286 |       end
287 |       n.subscribe second do |msg|
288 |         msgs[second] << String.new(msg.body)
289 |       end
290 |       n.publish first, "one"
291 |       n.publish first, "two"
292 |       n.publish second, "1"
293 |       n.publish second, "2"
294 | 
295 |       n.drain
296 | 
297 |       msgs.should eq({
298 |         first  => %w[one two],
299 |         second => %w[1 2],
300 |       })
301 |     ensure
302 |       n.close
303 |     end
304 |   end
305 | 
306 |   it "drains subscriptions before closing" do
307 |     n = NATS::Client.new
308 |     subject = UUID.random.to_s
309 |     greeting = nil
310 |     n.subscribe(subject) do |msg|
311 |       sleep 1.millisecond
312 |       greeting = String.new(msg.body)
313 |     end
314 |     n.flush
315 |     10.times { |i| n.publish subject, "hi #{i}" }
316 | 
317 |     n.close
318 | 
319 |     # 10 messages, 0..9
320 |     greeting.should eq "hi 9"
321 |   end
322 | 
323 |   it "connects to a server using NKeys" do
324 |     port = rand(50_000..60_000)
325 |     subject = UUID.random.to_s
326 | 
327 |     run_nats_on port, config: "nats_nkeys" do |client|
328 |       client.subscribe(subject) { |msg| client.reply msg, String.new(msg.body).upcase }
329 | 
330 |       response = client.request(subject, "hello").not_nil!
331 |       response.body.should eq "HELLO".to_slice
332 |     end
333 |   end
334 | 
335 |   it "reconnects if we hit too many pings" do
336 |     fake_nats_server = TCPServer.new("127.0.0.1", port: 0)
337 |     spawn do
338 |       until fake_nats_server.closed?
339 |         if client = fake_nats_server.accept?
340 |           client << "INFO "
341 |           {
342 |             server_id:   "lol",
343 |             server_name: "fake",
344 |             version:     "1.2.3.4",
345 |             go:          "fish",
346 |             host:        "0.0.0.0",
347 |             port:        0,
348 |             headers:     true,
349 |             max_payload: 2**20,
350 |             proto:       1,
351 |             client_id:   Random::Secure.rand(UInt64),
352 |           }.to_json client
353 |           client << "\r\n"
354 | 
355 |           # Read the CONNECT line
356 |           client.read_line.should start_with "CONNECT "
357 |           # Read the initial ping
358 |           client.read_line.should eq "PING"
359 |           # Respond to the initial ping to complete the handshake
360 |           client << "PONG\r\n"
361 |         end
362 |       end
363 |     end
364 | 
365 |     n = NATS::Client.new(
366 |       uri: URI.parse("nats://#{fake_nats_server.local_address.address}:#{fake_nats_server.local_address.port}"),
367 |       # The fake NATS server does not respond to pings beyond the initial one
368 |       # that completes the NATS connection, so we should be disconnected after
369 |       # the third ping is sent out at (50ms + latency) * 3 due to having too
370 |       # many outstanding pings
371 |       ping_interval: 20.milliseconds,
372 |       max_pings_out: 2,
373 |     )
374 |     disconnected = false
375 |     n.on_disconnect { disconnected = true }
376 |     pings = 0
377 |     n.on_ping do
378 |       pings += 1
379 |     end
380 | 
381 |     begin
382 |       sleep 50.milliseconds
383 |       # We have only send out 2 unanswered pings at this point, so we should
384 |       # not have tried to reconnect
385 |       disconnected.should eq false
386 |       pings.should eq 2
387 | 
388 |       sleep 40.milliseconds
389 |       # At this point, we should have sent too many unanswered pings and
390 |       # been disconnected.
391 |       disconnected.should eq true
392 |       pings.should eq 4
393 |     ensure
394 |       fake_nats_server.close
395 |     end
396 |   end
397 | end
398 | 
399 | private def run_nats_on(port : Int32, config : String, &)
400 |   Process.run "nats-server", args: "-js --port #{port} --config #{__DIR__}/support/#{config}.conf".split do |process|
401 |     wait_for_nats port
402 |     client = NATS::Client.new(
403 |       uri: URI.parse("nats://:#{port}"),
404 |       nkeys_file: "#{__DIR__}/support/#{config}.seed",
405 |     )
406 |     yield client
407 |   ensure
408 |     process.signal :term
409 |   end
410 | end
411 | 
412 | private def wait_for_nats(port : Int32, host : String = "127.0.0.1")
413 |   loop do
414 |     if socket = TCPSocket.new(host, port)
415 |       socket.close
416 |       return
417 |     end
418 |   rescue ex : IO::Error
419 |     sleep 10.milliseconds
420 |   end
421 | end
422 | 


--------------------------------------------------------------------------------
/src/objects.cr:
--------------------------------------------------------------------------------
  1 | require "digest"
  2 | 
  3 | require "./nats"
  4 | require "./jetstream"
  5 | require "./nuid"
  6 | require "./headers_converter"
  7 | 
  8 | module NATS
  9 |   # The NATS object store is S3-style object storage backed by NATS JetStream.
 10 |   #
 11 |   # You can access the object store API with `NATS::Client#objects`.
 12 |   #
 13 |   # Create a bucket with `Objects::Client#create_bucket`:
 14 |   #
 15 |   # ```
 16 |   # bucket = nats.objects.create_bucket("my-bucket")
 17 |   # ```
 18 |   #
 19 |   # Add an object from a file on disk (for example, from a tempfile created from an HTTP file upload) with `Objects::Bucket#put`:
 20 |   #
 21 |   # ```
 22 |   # File.open filename do |file|
 23 |   #   bucket.put "my-key", file
 24 |   # end
 25 |   # ```
 26 |   #
 27 |   # Get the metadata from an object in the store with `Objects::Bucket#get_info`:
 28 |   #
 29 |   # ```
 30 |   # bucket.get_info("my-key")
 31 |   # ```
 32 |   #
 33 |   # Get the contents of an object in the store with `Objects::Bucket#get`, which returns an `IO` instance that you can read from gradually to avoid having to load the entire object into memory. For example, for storing large images or videos.
 34 |   #
 35 |   # ```
 36 |   # if io = bucket.get("my-key")
 37 |   #   io.gets_to_end
 38 |   # end
 39 |   # ```
 40 |   @[Experimental("NATS object store is experimental and the API could change")]
 41 |   module Objects
 42 |     class Error < ::NATS::Error
 43 |     end
 44 | 
 45 |     class KeyError < Error
 46 |     end
 47 | 
 48 |     DEFAULT_CHUNK_SIZE = 128 * 1024 # 128KB
 49 | 
 50 |     class Client
 51 |       def initialize(@nats : NATS::Client)
 52 |       end
 53 | 
 54 |       # Create a bucket in the object store
 55 |       #
 56 |       # ```
 57 |       # bucket = nats.objects.create_bucket("my-bucket")
 58 |       # ```
 59 |       #
 60 |       # Give the bucket a description that will show up when you get bucket metadata
 61 |       # ```
 62 |       # bucket = nats.objects.create_bucket("uploads", description: "Storage for user uploads")
 63 |       # ```
 64 |       #
 65 |       # Set a maximum lifetime for your objects, after which they are deleted:
 66 |       # ```
 67 |       # bucket = nats.objects.create_bucket("snapchat-images", ttl: 1.day)
 68 |       # ```
 69 |       #
 70 |       # Replicate your objects across multiple NATS servers in your cluster:
 71 |       # ```
 72 |       # bucket = nats.objects.create_bucket("durable-storage", replicas: 3)
 73 |       # ```
 74 |       def create_bucket(
 75 |         name : String,
 76 |         description : String = "",
 77 |         *,
 78 |         ttl : Time::Span? = nil,
 79 |         storage : JetStream::StreamConfig::Storage = :file,
 80 |         replicas : Int? = nil,
 81 |         max_bytes : Int? = nil,
 82 |         placement : JetStream::StreamConfig::Placement? = nil,
 83 |       )
 84 |         stream = @nats.jetstream.stream.create(
 85 |           name: "OBJ_#{name}",
 86 |           description: description,
 87 |           subjects: [
 88 |             "$O.#{name}.C.>", # Object chunks
 89 |             "$O.#{name}.M.>", # Metadata
 90 |           ],
 91 |           max_age: ttl,
 92 |           max_bytes: max_bytes,
 93 |           storage: storage,
 94 |           discard: :new,
 95 |           allow_rollup_headers: true,
 96 |           placement: placement,
 97 |         )
 98 | 
 99 |         Bucket.new(stream, self)
100 |       end
101 | 
102 |       def get_bucket(name : String)
103 |         if stream = @nats.jetstream.stream.info("OBJ_#{name}")
104 |           Bucket.new(stream, self)
105 |         end
106 |       end
107 | 
108 |       def delete_bucket(name : String)
109 |         @nats.jetstream.stream.delete "OBJ_#{name}"
110 |       end
111 | 
112 |       def put(bucket : String, key : String, value : IO, description : String? = nil, headers : Headers = Headers.new, chunk_size : Int = DEFAULT_CHUNK_SIZE)
113 |         existing = get_info(bucket, key)
114 |         id = NUID.next
115 |         stream_name = "OBJ_#{bucket}"
116 |         chunk_subject = "$O.#{bucket}.C.#{id}"
117 |         meta_subject = "$O.#{bucket}.M.#{sanitize_key(key)}"
118 |         chunk = Bytes.new(chunk_size)
119 |         sha = Digest::SHA256.new
120 |         sent = 0
121 |         total = 0i64
122 | 
123 |         begin
124 |           while (count = value.read(chunk)) != 0
125 |             body = chunk[0...count]
126 |             sha << body
127 | 
128 |             @nats.publish chunk_subject, body
129 |             sent += 1
130 |             total += count
131 |           end
132 | 
133 |           msg = ObjectInfo.new(
134 |             bucket: bucket,
135 |             name: key,
136 |             description: description,
137 |             headers: headers,
138 |             nuid: id,
139 |             size: total,
140 |             mtime: Time.utc,
141 |             chunks: sent,
142 |             digest: "SHA-256=#{Base64.urlsafe_encode(sha.final)}",
143 |           )
144 |           @nats.jetstream.publish "$O.#{bucket}.M.#{sanitize_key(key)}",
145 |             body: msg.to_json,
146 |             headers: Headers{"Nats-Rollup" => "sub"}
147 |         rescue ex
148 |           @nats.jetstream.stream.purge stream_name, subject: chunk_subject
149 |           raise ex
150 |         end
151 | 
152 |         if existing
153 |           @nats.jetstream.stream.purge stream_name, subject: "$O.#{bucket}.C.#{existing.nuid}"
154 |         end
155 | 
156 |         @nats.flush
157 |         msg
158 |       end
159 | 
160 |       def get_info(bucket : String, key : String)
161 |         get_info bucket, pattern: sanitize_key(key)
162 |       end
163 | 
164 |       def get_info(bucket : String, *, pattern : String)
165 |         meta = "$O.#{bucket}.M.#{pattern}"
166 |         stream = "OBJ_#{bucket}"
167 |         if response = @nats.jetstream.stream.get_msg(stream, last_by_subject: meta)
168 |           info = ObjectInfo.from_json(String.new(response.message.data))
169 |           info.mtime = response.message.time
170 |           info
171 |         end
172 |       end
173 | 
174 |       def get(bucket : String, key : String) : IO?
175 |         return unless info = get_info(bucket, key)
176 |         key = sanitize_key(key)
177 | 
178 |         subject = "NATS.Objects.#{bucket}.data.#{key}.get.#{NUID.next}"
179 |         consumer = @nats.jetstream.consumer.create(
180 |           stream_name: "OBJ_#{bucket}",
181 |           filter_subject: "$O.#{bucket}.C.#{info.nuid}",
182 |           deliver_subject: subject,
183 |           ack_policy: :none,
184 |           max_deliver: 1,
185 |           flow_control: true,
186 |           idle_heartbeat: 5.seconds, # Required for flow control
187 |         )
188 |         read, write = IO.pipe
189 |         chunks = 0
190 |         @nats.subscribe(subject) do |msg, subscription|
191 |           if msg.body.empty? && (headers = msg.headers) && headers["Status"]? == "100 FlowControl Request"
192 |             # Once we ack the flow-control message, we will receive more data.
193 |             # Because we're using IO.pipe, we don't have to implement flow
194 |             # control ourselves here. We get it for free because these pipes
195 |             # have a buffer size that will automatically block the write call
196 |             # below if that buffer fills up.
197 |             @nats.reply msg, "" if msg.reply_to
198 |           else
199 |             # TODO: ensure we get *all* chunks
200 |             write.write msg.body
201 |             chunks += 1
202 |           end
203 | 
204 |           if chunks >= info.chunks
205 |             write.close
206 |             @nats.jetstream.consumer.delete consumer
207 |             @nats.unsubscribe subscription
208 |           end
209 |         rescue ex : IO::Error
210 |           write.close
211 |           @nats.jetstream.consumer.delete consumer
212 |           @nats.unsubscribe subscription
213 |         end
214 |         read
215 |       end
216 | 
217 |       def keys(bucket : String, pattern : String = ">") : Set(String)
218 |         keys = Set(String).new
219 | 
220 |         # If there are no messages in the stream with this pattern, just return
221 |         # the empty set of keys. Otherwise, we will end up sitting here waiting
222 |         # for keys to come streaming in.
223 |         return keys if get_info(bucket, pattern: pattern).nil?
224 | 
225 |         # Look at all the keys in the current bucket
226 |         watch bucket, pattern: pattern do |msg, watch|
227 |           keys << msg.name
228 | 
229 |           watch.stop if watch.pending == 0
230 |         end
231 | 
232 |         keys
233 |       end
234 | 
235 |       def watch(
236 |         bucket : String,
237 |         key : String,
238 |         &block : ObjectInfo, Watch ->
239 |       )
240 |         watch bucket, pattern: sanitize_key(key), &block
241 |       end
242 | 
243 |       def watch(
244 |         bucket : String,
245 |         *,
246 |         pattern : String,
247 |         &block : ObjectInfo, Watch ->
248 |       )
249 |         stop_channel = Channel(Nil).new
250 |         watch = Watch.new(stop_channel)
251 |         inbox = "$WATCH_INBOX.#{NUID.next}"
252 |         deliver_group = NUID.next
253 | 
254 |         stream_name = "OBJ_#{bucket}"
255 |         consumer = @nats.jetstream.consumer.create(
256 |           stream_name: stream_name,
257 |           deliver_subject: inbox,
258 |           deliver_group: deliver_group,
259 |           deliver_policy: :last_per_subject,
260 |           filter_subject: "$O.#{bucket}.M.#{pattern}",
261 |           ack_policy: :none,
262 |         )
263 |         subscription = @nats.subscribe inbox, queue_group: deliver_group do |msg|
264 |           js_msg = JetStream::Message.new(msg)
265 |           watch.pending = js_msg.pending
266 | 
267 |           _, bucket_name, _, key_name = msg.subject.split('.', 4)
268 |           info = ObjectInfo.from_json String.new msg.body
269 | 
270 |           block.call info, watch
271 |         end
272 | 
273 |         stop_channel.receive
274 |       ensure
275 |         if subscription
276 |           @nats.unsubscribe subscription
277 |         end
278 |         if stream_name && consumer && (name = consumer.name)
279 |           @nats.jetstream.consumer.delete stream_name, name
280 |         end
281 |       end
282 | 
283 |       struct Watch
284 |         property pending : Int64 = 0
285 | 
286 |         def initialize(@stop_channel : Channel(Nil))
287 |         end
288 | 
289 |         def stop
290 |           @stop_channel.send nil
291 |         end
292 |       end
293 | 
294 |       struct ObjectInfo
295 |         include JSON::Serializable
296 | 
297 |         getter bucket : String
298 |         getter name : String
299 |         getter description : String?
300 |         @[JSON::Field(converter: NATS::HeadersConverter)]
301 |         getter headers : Headers { Headers.new }
302 |         getter nuid : String
303 |         getter size : Int64
304 |         property mtime : Time
305 |         getter chunks : Int32
306 |         getter digest : String?
307 |         getter deleted : Bool?
308 | 
309 |         def initialize(*, @bucket, @name, @description, @headers, @nuid, @size, @chunks, @digest, @mtime = Time.new(0, 0), @deleted = nil)
310 |         end
311 | 
312 |         def digest!
313 |           digest.not_nil!
314 |         end
315 |       end
316 | 
317 |       private def sanitize_key(key : String)
318 |         Base64.urlsafe_encode key
319 |       end
320 |     end
321 | 
322 |     struct Bucket
323 |       getter name : String
324 |       getter stream_name : String
325 |       @client : Objects::Client
326 | 
327 |       def self.new(stream : JetStream::Stream, client : Objects::Client)
328 |         new(
329 |           name: stream.config.name.lchop("OBJ_"),
330 |           stream_name: stream.config.name,
331 |           client: client,
332 |         )
333 |       end
334 | 
335 |       def initialize(@name, @stream_name, @client)
336 |       end
337 | 
338 |       def put(key : String, value : String | Bytes, **kwargs)
339 |         put(key, IO::Memory.new(value), **kwargs)
340 |       end
341 | 
342 |       def put(key : String, value : IO, *, description : String? = nil, headers : Headers = Headers.new, chunk_size : Int = DEFAULT_CHUNK_SIZE)
343 |         @client.put(name, key, value, description: description, headers: headers, chunk_size: chunk_size)
344 |       end
345 | 
346 |       def get_info!(key : String)
347 |         if info = get_info(key)
348 |           info
349 |         else
350 |           raise KeyError.new("Key #{key.inspect} does not exist for object bucket #{name.inspect}")
351 |         end
352 |       end
353 | 
354 |       def get_info(key : String)
355 |         @client.get_info name, key
356 |       end
357 | 
358 |       def get!(key : String)
359 |         if result = get(key)
360 |           result
361 |         else
362 |           raise KeyError.new("Key #{key.inspect} does not exist for object bucket #{name.inspect}")
363 |         end
364 |       end
365 | 
366 |       def get(key : String)
367 |         @client.get name, key
368 |       end
369 | 
370 |       def keys(pattern : String = ">")
371 |         @client.keys name, pattern
372 |       end
373 |     end
374 |   end
375 | 
376 |   class Client
377 |     getter objects : Objects::Client { Objects::Client.new(self) }
378 |   end
379 | end
380 | 


--------------------------------------------------------------------------------
/src/services.cr:
--------------------------------------------------------------------------------
  1 | require "./nats"
  2 | require "./nuid"
  3 | 
  4 | module NATS
  5 |   # The [NATS Services API](https://docs.nats.io/using-nats/developer/services)
  6 |   # allows you to build microservices using NATS instead of HTTP. Since NATS has
  7 |   # the concept of request/reply messages through a decentralized message broker,
  8 |   # you don't need to deal with domain names, load-balancing, service meshes, or
  9 |   # other concepts that you might have to implement in HTTP-based microservices. NATS takes care of all of those for you.
 10 |   #
 11 |   # ```
 12 |   # inventory = nats.services.add "inventory",
 13 |   #   version: "0.1.0",
 14 |   #   description: "Manage store inventory"
 15 |   #
 16 |   # # Add the top-level subject namespace for the service
 17 |   # inventory.add_group "inventory" do |inv|
 18 |   #   # Add a namespace specifically for managing products
 19 |   #   inv.add_group "products" do |products|
 20 |   #     # Create a product. Receives a CreateProductRequest and returns a Product.
 21 |   #     # Example using the NATS CLI:
 22 |   #     #   nats req inventory.products.create '{"name":"Computer","description":"It is a computer","price_cents":200000}'
 23 |   #     products.add_endpoint "create" do |request|
 24 |   #       # Deserialize the request body and make a product out of it
 25 |   #       product = CreateProductRequest.from_json(request.data_string).product
 26 |   #       # Save the product to our KV store
 27 |   #       products_kv[product.id.to_s] = product.to_json
 28 |   #       # Reply with the serialized product
 29 |   #       nats.reply request, product.to_json
 30 |   #     end
 31 |   #
 32 |   #     # Return the product with the given id passed in the subject.
 33 |   #     # Example: inventory.products.get.0197e31f-3ffa-7fd7-8512-a331a20e5ae3
 34 |   #     # Equivalent to the following HTTP request:
 35 |   #     #   GET /inventory/products/0197e31f-3ffa-7fd7-8512-a331a20e5ae3
 36 |   #     products.add_endpoint "show", subject: "get.*" do |request|
 37 |   #       # Split the subject to get the id
 38 |   #       _, _, _, product_id = request.subject.split('.')
 39 |   #
 40 |   #       # Fetch the product from the `inventory-products` KV bucket
 41 |   #       nats.reply request, products_kv[product_id]
 42 |   #     end
 43 |   #   end
 44 |   # end
 45 |   # ```
 46 |   class Services
 47 |     @nats : Client
 48 | 
 49 |     NAME_PATTERN = /\A[\w\-]+\z/
 50 | 
 51 |     # :nodoc:
 52 |     def initialize(@nats)
 53 |     end
 54 | 
 55 |     # Register a service with the NATS server.
 56 |     #
 57 |     # ```
 58 |     # inventory = nats.services.add "inventory",
 59 |     #   version: "0.1.0",
 60 |     #   description: "Manage inventory"
 61 |     # ```
 62 |     def add(name : String, *, version : String, description : String, metadata : Hash(String, String) = {} of String => String)
 63 |       unless name =~ NAME_PATTERN
 64 |         raise ArgumentError.new("NATS service names may only contain A-Z, a-z, 0-9, dash, and underscore characters.")
 65 |       end
 66 |       started = Time.utc.to_rfc3339
 67 |       id = NUID.next
 68 |       service = Service.new(
 69 |         nats: @nats,
 70 |         id: id,
 71 |         name: name,
 72 |         version: version,
 73 |         description: description,
 74 |         metadata: metadata,
 75 |       )
 76 | 
 77 |       [
 78 |         "$SRV.PING",
 79 |         "$SRV.PING.#{name}",
 80 |         "$SRV.PING.#{name}.#{id}",
 81 |       ].each do |subject|
 82 |         service.subscriptions << @nats.subscribe subject do |msg|
 83 |           @nats.reply msg, {
 84 |             type:     "io.nats.micro.v1.ping_response",
 85 |             name:     name,
 86 |             id:       id,
 87 |             version:  version,
 88 |             metadata: metadata,
 89 |           }.to_json
 90 |         end
 91 |       end
 92 | 
 93 |       [
 94 |         "$SRV.STATS",
 95 |         "$SRV.STATS.#{name}",
 96 |         "$SRV.STATS.#{name}.#{id}",
 97 |       ].each do |subject|
 98 |         service.subscriptions << @nats.subscribe subject do |msg|
 99 |           @nats.reply msg, {
100 |             type:      "io.nats.micro.v1.stats_response",
101 |             name:      name,
102 |             id:        id,
103 |             version:   version,
104 |             metadata:  metadata,
105 |             endpoints: service.endpoint_stats,
106 |             started:   started,
107 |           }.to_json
108 |         end
109 |       end
110 | 
111 |       [
112 |         "$SRV.INFO",
113 |         "$SRV.INFO.#{name}",
114 |         "$SRV.INFO.#{name}.#{id}",
115 |       ].each do |subject|
116 |         service.subscriptions << @nats.subscribe subject do |msg|
117 |           @nats.reply msg, {
118 |             type:        "io.nats.micro.v1.info_response",
119 |             name:        name,
120 |             id:          id,
121 |             version:     version,
122 |             description: description,
123 |             metadata:    metadata,
124 |             endpoints:   service.endpoint_info,
125 |           }.to_json
126 |         end
127 |       end
128 | 
129 |       service
130 |     end
131 |   end
132 | 
133 |   # The `Service` represents a NATS service that was created by the `Services`
134 |   # API. It exists to hang your endpoints on:
135 |   #
136 |   # ```
137 |   # inventory = nats.services.add "inventory",
138 |   #   version: "0.1.0",
139 |   #   description: "Manage inventory"
140 |   # inventory.add_endpoint "inventory.products.get", subject: "inventory.products.get.*" do |request|
141 |   #   _, _, _, id
142 |   #   nats.reply request, ProductQuery.new.find(id).to_json
143 |   # end
144 |   # ```
145 |   class Service
146 |     @nats : Client
147 |     getter id : String
148 |     getter name : String
149 |     getter version : String
150 |     getter description : String
151 |     getter metadata : Hash(String, String)
152 |     getter subscriptions : Array(Subscription)
153 |     getter endpoints : Array(Endpoint) = [] of Endpoint
154 |     @groups = [] of Group
155 |     protected getter error_handler : ErrorHandler
156 | 
157 |     alias ErrorHandler = Exception, Message ->
158 | 
159 |     # :nodoc:
160 |     def initialize(@nats, @id, @name, @version, @description, @metadata, @subscriptions = [] of Subscription)
161 |       @error_handler = ErrorHandler.new do |error, message|
162 |         @nats.reply message, "",
163 |           headers: Headers{
164 |             "Nats-Service-Error-Code" => "500",
165 |             "Nats-Service-Error"      => error.message.try(&.gsub(/\s+/, ' ')) || "Internal error",
166 |           }
167 |       end
168 |     end
169 | 
170 |     # ```
171 |     # service.add_endpoint "endpoint-name", subject: "endpoint.subject" do |request|
172 |     #   nats.reply request, "reply goes here"
173 |     # end
174 |     # ```
175 |     def add_endpoint(
176 |       name : String,
177 |       *,
178 |       subject : String = name,
179 |       queue_group : String = "q",
180 |       concurrency : Int = 1,
181 |       &block : Message, Subscription ->
182 |     ) : Endpoint
183 |       unless name =~ Services::NAME_PATTERN
184 |         raise ArgumentError.new("Endpoint names can only contain letter, number, dash, and underscore characters")
185 |       end
186 | 
187 |       endpoint = uninitialized Endpoint
188 |       subscription = @nats.subscribe subject, queue_group: queue_group, concurrency: concurrency do |msg, subscription|
189 |         endpoint.request msg do
190 |           block.call msg, subscription
191 |         end
192 |       end
193 | 
194 |       endpoint = Endpoint.new(
195 |         nats: @nats,
196 |         service: self,
197 |         name: name,
198 |         subject: subject,
199 |         queue_group: queue_group,
200 |         subscription: subscription,
201 |       )
202 |       endpoints << endpoint
203 | 
204 |       endpoint
205 |     end
206 | 
207 |     # Add a `Group` and yield it to the block.
208 |     #
209 |     # ```
210 |     # service.add_group "products" do |inventory|
211 |     #   inventory.add_endpoint "create" do |request|
212 |     #     nats.reply request, "reply goes here"
213 |     #   end
214 |     # end
215 |     # ```
216 |     def add_group(name : String, &)
217 |       yield add_group(name)
218 |     end
219 | 
220 |     # Add a `Group` of endpoints.
221 |     def add_group(name : String)
222 |       group = Group.new(@nats, self, name)
223 |       @groups << group
224 |       group
225 |     end
226 | 
227 |     def error_reply(
228 |       request : Message,
229 |       body : String | Bytes = "",
230 |       *,
231 |       error : String,
232 |       error_code : String | Int,
233 |     ) : Nil
234 |       @nats.reply request, body, headers: Headers{
235 |         "Nats-Service-Error"      => error,
236 |         "Nats-Service-Error-Code" => error_code.to_s,
237 |       }
238 |     end
239 | 
240 |     # Execute the given block for all exceptions raised in this service's
241 |     # endpoints. This is useful for returning a common error response.
242 |     #
243 |     # ```
244 |     # service.on_error do |exception, message|
245 |     #   nats.reply message, "", headers: NATS::Headers{
246 |     #     "Nats-Service-Error-Code" => "500",
247 |     #     "Nats-Service-Error"      => "Unexpected error: #{exception.message}",
248 |     #   }
249 |     # end
250 |     # ```
251 |     def on_error(&@error_handler : ErrorHandler)
252 |       self
253 |     end
254 | 
255 |     # :nodoc:
256 |     def endpoint_stats
257 |       endpoints.map do |endpoint|
258 |         {
259 |           name:                    endpoint.name,
260 |           subject:                 endpoint.subject,
261 |           queue_group:             endpoint.queue_group,
262 |           num_requests:            endpoint.total_requests,
263 |           num_errors:              endpoint.total_errors,
264 |           last_error:              endpoint.last_error,
265 |           data:                    nil,
266 |           processing_time:         endpoint.total_processing_time.total_nanoseconds.to_i64,
267 |           average_processing_time: endpoint.average_processing_time.total_nanoseconds.to_i64,
268 |         }
269 |       end
270 |     end
271 | 
272 |     # :nodoc:
273 |     def endpoint_info
274 |       endpoints.map do |endpoint|
275 |         {
276 |           type:        "io.nats.micro.v1.info_response",
277 |           name:        endpoint.name,
278 |           subject:     endpoint.subject,
279 |           queue_group: endpoint.queue_group,
280 |         }
281 |       end
282 |     end
283 | 
284 |     # The  `Group` represents a cohesive group of endpoints. Groups are useful
285 |     # for applying a common prefix to subjects or setting a common queue group.
286 |     class Group
287 |       @nats : Client
288 |       getter service : Service
289 |       getter name : String
290 | 
291 |       # :nodoc:
292 |       def initialize(@nats, @service, @name)
293 |       end
294 | 
295 |       def add_endpoint(
296 |         name : String,
297 |         *,
298 |         subject : String = name,
299 |         queue_group : String = "q",
300 |         concurrency : Int = 1,
301 |         &block : Message, Subscription ->
302 |       ) : Endpoint
303 |         service.add_endpoint name,
304 |           subject: "#{@name}.#{subject}",
305 |           queue_group: queue_group,
306 |           concurrency: concurrency,
307 |           &block
308 |       end
309 | 
310 |       def add_group(name : String, &)
311 |         yield add_group(name)
312 |       end
313 | 
314 |       def add_group(name : String)
315 |         Group.new(@nats, @service, "#{@name}.#{name}")
316 |       end
317 |     end
318 | 
319 |     # The `Endpoint` is the request handler. You generally won't interact with
320 |     # this class directly.
321 |     class Endpoint
322 |       @nats : Client
323 |       getter service : Service
324 |       getter name : String
325 |       getter subject : String
326 |       getter queue_group : String
327 |       getter subscription : Subscription
328 |       @total_requests : Atomic(Int64) = Atomic.new(0i64)
329 |       @total_errors : Atomic(Int64) = Atomic.new(0i64)
330 |       @total_processing_nanoseconds : Atomic(Int64) = Atomic.new(0i64)
331 |       getter last_error : String?
332 |       protected getter error_handler : ErrorHandler
333 | 
334 |       # :nodoc:
335 |       def initialize(@nats, @service, @name, @subject, @queue_group, @subscription)
336 |         @error_handler = @service.error_handler
337 |       end
338 | 
339 |       def total_requests
340 |         @total_requests.get
341 |       end
342 | 
343 |       def total_errors
344 |         @total_errors.get
345 |       end
346 | 
347 |       def total_processing_time
348 |         @total_processing_nanoseconds.get.nanoseconds
349 |       end
350 | 
351 |       def average_processing_time
352 |         requests = total_requests
353 |         return 0.seconds if requests.zero?
354 | 
355 |         total_processing_time / total_requests
356 |       end
357 | 
358 |       protected def request(message : Message, &)
359 |         start = Time.monotonic
360 |         begin
361 |           yield
362 |         rescue ex
363 |           @total_errors.add 1
364 |           @last_error = ex.message || ex.class.name
365 |           @error_handler.call ex, message
366 |           raise ex
367 |         ensure
368 |           @total_requests.add 1
369 |           @total_processing_nanoseconds.add (Time.monotonic - start).total_nanoseconds.to_i64
370 |         end
371 |       end
372 |     end
373 |   end
374 | 
375 |   class Client
376 |     getter services : Services { Services.new self }
377 |   end
378 | end
379 | 


--------------------------------------------------------------------------------
/spec/jetstream_spec.cr:
--------------------------------------------------------------------------------
  1 | require "./spec_helper"
  2 | require "../src/jetstream"
  3 | require "uuid"
  4 | require "wait_group"
  5 | 
  6 | private macro create_stream(subjects, **stream_options)
  7 |   nats.jetstream.stream.create(
  8 |     name: "test-stream-#{UUID.random}",
  9 |     subjects: {{subjects}},
 10 |     storage: :memory,
 11 |     {{stream_options.double_splat}}
 12 |   )
 13 | end
 14 | 
 15 | private macro create_consumer(stream, deliver_subject = UUID.random.to_s)
 16 |   nats.jetstream.consumer.create(
 17 |     stream_name: stream.config.name,
 18 |     deliver_group: UUID.random.to_s,
 19 |     deliver_subject: {{deliver_subject}},
 20 |     memory_storage: true,
 21 |   )
 22 | end
 23 | 
 24 | nats = NATS::Client.new
 25 |   .on_error { |ex| Log.for(NATS).error(exception: ex) }
 26 | js = nats.jetstream
 27 | 
 28 | private macro test(name, stream_options = {} of String => String, **options)
 29 |   it({{name}}, {{options.double_splat}}) do
 30 |     write_subject = UUID.random.to_s
 31 |     stream = create_stream([write_subject], {{stream_options.double_splat}})
 32 | 
 33 |     begin
 34 |       {{yield}}
 35 |     ensure
 36 |       js.stream.delete stream
 37 |     end
 38 |   end
 39 | end
 40 | 
 41 | private struct CounterResponse
 42 |   include JSON::Serializable
 43 |   @[JSON::Field(key: "val", converter: CounterResponse::ValueConverter)]
 44 |   getter value : Int64
 45 | 
 46 |   module ValueConverter
 47 |     def self.from_json(json : JSON::PullParser)
 48 |       json.read_string.to_i64
 49 |     end
 50 |   end
 51 | end
 52 | 
 53 | describe NATS::JetStream do
 54 |   it "creates, lists, and deletes streams" do
 55 |     uuid = UUID.random
 56 |     included = nats.jetstream.stream.create(
 57 |       name: "included-#{uuid}",
 58 |       subjects: ["test.jetstream.included.#{uuid}.*"],
 59 |       storage: :memory,
 60 |     )
 61 |     excluded = nats.jetstream.stream.create(
 62 |       name: "excluded-#{uuid}",
 63 |       subjects: ["test.jetstream.excluded.#{uuid}.*"],
 64 |       storage: :memory,
 65 |     )
 66 | 
 67 |     begin
 68 |       included.config.name.should eq "included-#{uuid}"
 69 |       all = nats.jetstream.stream.list.streams
 70 |       filtered = nats.jetstream.stream.list(subject: "test.jetstream.included.#{uuid}.*").streams
 71 |       all.should contain included
 72 |       all.should contain excluded
 73 | 
 74 |       filtered.should contain included
 75 |       filtered.should_not contain excluded
 76 |     ensure
 77 |       nats.jetstream.stream.delete included
 78 |       nats.jetstream.stream.delete excluded
 79 | 
 80 |       nats.jetstream.stream.list.streams.should_not contain included
 81 |       nats.jetstream.stream.list.streams.should_not contain excluded
 82 |     end
 83 |   end
 84 | 
 85 |   pending "paginates streams" do
 86 |     a_bunch_of_streams = [] of NATS::JetStream::Stream
 87 |     # Create 1k streams concurrently and store them in the array
 88 |     WaitGroup.wait do |wg|
 89 |       mutex = Mutex.new
 90 |       1_000.times do |id|
 91 |         wg.spawn do
 92 |           stream = js.stream.create(
 93 |             name: "test-#{id}",
 94 |             storage: :memory,
 95 |             subjects: ["test.jetstream.pagination.#{id}"],
 96 |           )
 97 |           mutex.synchronize { a_bunch_of_streams << stream }
 98 |         end
 99 |       end
100 |     end
101 | 
102 |     begin
103 |       streams = js.stream.list.to_a
104 |       streams.size.should eq a_bunch_of_streams.size
105 |       a_bunch_of_streams.each do |stream|
106 |         streams.map(&.config.name).should contain stream.config.name
107 |       end
108 |     ensure
109 |       a_bunch_of_streams.each do |stream|
110 |         js.stream.delete stream
111 |       end
112 |     end
113 |   end
114 | 
115 |   it "creates and deletes streams" do
116 |     subjects = [UUID.random.to_s]
117 |     stream = create_stream(subjects)
118 | 
119 |     begin
120 |     ensure
121 |       nats.jetstream.stream.delete stream
122 |       nats.jetstream.stream.list.streams.should_not contain stream
123 |     end
124 |   end
125 | 
126 |   it "publishes to streams and reads with push consumers" do
127 |     write_subject = UUID.random.to_s
128 |     stream = create_stream([write_subject])
129 | 
130 |     consumer_name = UUID.random.to_s
131 |     read_subject = UUID.random.to_s
132 |     deliver_group = UUID.random.to_s
133 | 
134 |     consumer = nats.jetstream.consumer.create(
135 |       stream_name: stream.config.name,
136 |       durable_name: consumer_name,
137 |       deliver_group: deliver_group,
138 |       deliver_subject: read_subject,
139 |       ack_policy: :none,
140 |     )
141 | 
142 |     begin
143 |       js.publish write_subject, "hello"
144 |       channel = Channel(NATS::JetStream::Message).new
145 | 
146 |       msg_subject = nil
147 |       msg_body = nil
148 |       nats.jetstream.subscribe consumer do |msg|
149 |         channel.send msg
150 |       end
151 | 
152 |       select
153 |       when msg = channel.receive
154 |         msg.subject.should eq write_subject
155 |         msg.body.should eq "hello".to_slice
156 |       when timeout(2.seconds)
157 |         raise "Did not receive message within 2 seconds"
158 |       end
159 |     ensure
160 |       nats.jetstream.stream.delete stream
161 |     end
162 |   end
163 | 
164 |   describe "acknowledging" do
165 |     it "acknowledges messages" do
166 |       write_subject = UUID.random.to_s
167 |       stream = create_stream([write_subject])
168 |       consumer = create_consumer(stream)
169 |       channel = Channel(NATS::JetStream::Message).new
170 |       nats.jetstream.publish write_subject, "omg"
171 | 
172 |       begin
173 |         nats.jetstream.subscribe consumer do |msg|
174 |           nats.jetstream.ack msg
175 |           nats.flush
176 |           channel.send msg
177 |           channel.close
178 |         end
179 | 
180 |         msg = channel.receive
181 |         consumer = nats.jetstream.consumer.info!(consumer.stream_name, consumer.name)
182 |         consumer.ack_floor.consumer_seq.should eq 1
183 |       ensure
184 |         nats.jetstream.stream.delete stream
185 |       end
186 |     end
187 | 
188 |     it "can wait for double-acknowledgement from the server" do
189 |       write_subject = UUID.random.to_s
190 |       stream = create_stream([write_subject])
191 |       consumer = create_consumer(stream)
192 |       nats.jetstream.publish write_subject, "omg"
193 |       channel = Channel(NATS::JetStream::Message).new
194 | 
195 |       begin
196 |         nats.jetstream.subscribe consumer do |msg|
197 |           nats.jetstream.ack_sync msg
198 |           channel.send msg
199 |         end
200 | 
201 |         msg = channel.receive
202 |         consumer = nats.jetstream.consumer.info!(consumer.stream_name, consumer.name)
203 |         consumer.ack_floor.consumer_seq.should eq 1
204 |       ensure
205 |         nats.jetstream.stream.delete stream
206 |       end
207 |     end
208 | 
209 |     it "can wait for double-ack for a list of messages" do
210 |       successful = [] of NATS::JetStream::Message
211 |       write_subject = UUID.random.to_s
212 |       channel = Channel(NATS::JetStream::Message).new
213 |       stream = create_stream([write_subject])
214 |       consumer = create_consumer(stream)
215 |       count = 10
216 |       count.times { |i| nats.publish write_subject, i.to_s }
217 | 
218 |       begin
219 |         nats.jetstream.subscribe consumer do |msg|
220 |           channel.send msg
221 |         end
222 | 
223 |         count.times { successful << channel.receive }
224 |         nats.jetstream.ack_sync(successful).should eq count
225 |       ensure
226 |         nats.jetstream.stream.delete stream
227 |       end
228 |     end
229 | 
230 |     it "can negatively acknowledge (reject) a message" do
231 |       write_subject = UUID.random.to_s
232 |       stream = create_stream([write_subject])
233 |       consumer = create_consumer(stream)
234 |       nats.jetstream.publish write_subject, "omg"
235 |       channel = Channel(NATS::JetStream::Message).new
236 | 
237 |       begin
238 |         nats.jetstream.subscribe consumer do |msg|
239 |           nats.jetstream.nack msg
240 |           nats.flush
241 |           channel.send msg
242 |         end
243 | 
244 |         msg = channel.receive
245 |         consumer = nats.jetstream.consumer.info!(consumer.stream_name, consumer.name)
246 |         consumer.ack_floor.consumer_seq.should eq 0
247 |         consumer.num_ack_pending.should eq 1
248 |         consumer.num_redelivered.should eq 1
249 |       ensure
250 |         nats.jetstream.stream.delete stream
251 |       end
252 |     end
253 | 
254 |     it "can tell the server it needs more time with a WIP ack" do
255 |       write_subject = UUID.random.to_s
256 |       stream = create_stream([write_subject])
257 |       consumer = create_consumer(stream)
258 |       nats.jetstream.publish write_subject, "omg"
259 |       channel = Channel(NATS::JetStream::Message).new
260 | 
261 |       begin
262 |         nats.jetstream.subscribe consumer do |msg|
263 |           nats.jetstream.in_progress msg
264 |           nats.flush
265 |           channel.send msg
266 |         end
267 | 
268 |         msg = channel.receive
269 |         consumer = nats.jetstream.consumer.info!(consumer.stream_name, consumer.name)
270 |         consumer.ack_floor.consumer_seq.should eq 0
271 |         consumer.num_ack_pending.should eq 1
272 |         consumer.num_redelivered.should eq 0
273 |       ensure
274 |         nats.jetstream.stream.delete stream
275 |       end
276 |     end
277 | 
278 |     it "can ack a pull message and receive the next in the same request" do
279 |       write_subject = UUID.random.to_s
280 |       stream = create_stream([write_subject])
281 |       consumer = create_consumer(stream, deliver_subject: nil)
282 |       3.times do |i|
283 |         nats.jetstream.publish write_subject, (i + 1).to_s
284 |       end
285 | 
286 |       begin
287 |         count = 0
288 |         pull = nats.jetstream.pull_subscribe(consumer)
289 |         msg = pull.fetch(1).first
290 |         while msg = pull.ack_next(msg, timeout: 100.milliseconds)
291 |           count += 1
292 |         end
293 | 
294 |         count.should eq 2
295 |       ensure
296 |         nats.jetstream.stream.delete stream
297 |       end
298 |     end
299 |   end
300 | 
301 |   it "can unsubscribe from a consumer within the message block" do
302 |     write_subject = UUID.random.to_s
303 |     stream = create_stream([write_subject])
304 |     consumer_name = UUID.random.to_s
305 |     consumer = create_consumer(stream, deliver_subject: consumer_name)
306 |     3.times do |i|
307 |       nats.jetstream.publish write_subject, i.to_s
308 |     end
309 |     received = 0
310 | 
311 |     sub = nats.jetstream.subscribe consumer do |msg, subscription|
312 |       received += 1
313 |       subscription.close if msg.pending == 0
314 |     end
315 | 
316 |     start = Time.monotonic
317 |     until sub.closed?
318 |       sleep 10.milliseconds
319 |       if Time.monotonic - start >= 1.second
320 |         raise "Timed out waiting for subscription to close. Received #{received} messages"
321 |       end
322 |     end
323 |   end
324 | 
325 |   it "gets idle heartbeats" do
326 |     write_subject = UUID.random.to_s
327 |     stream = create_stream([write_subject])
328 |     consumer_name = UUID.random.to_s
329 |     deliver_group = UUID.random.to_s
330 |     consumer = nats.jetstream.consumer.create(
331 |       stream_name: stream.config.name,
332 |       deliver_subject: consumer_name,
333 |       deliver_group: deliver_group,
334 |       idle_heartbeat: 150.milliseconds,
335 |     )
336 |     10.times { nats.publish write_subject, "hi" }
337 |     nats.jetstream.subscribe consumer do |msg|
338 |       nats.jetstream.ack_sync msg
339 |     end
340 | 
341 |     sleep 250.milliseconds
342 | 
343 |     nats.jetstream.stream.delete stream
344 |   end
345 | 
346 |   it "reads from durable pull consumers" do
347 |     write_subject = UUID.random.to_s
348 |     stream = create_stream([write_subject])
349 | 
350 |     consumer_name = UUID.random.to_s
351 |     deliver_group = UUID.random.to_s
352 | 
353 |     consumer = nats.jetstream.consumer.create(
354 |       stream_name: stream.config.name,
355 |       durable_name: consumer_name,
356 |       deliver_group: deliver_group,
357 |     )
358 | 
359 |     pull = nats.jetstream.pull_subscribe(consumer)
360 | 
361 |     begin
362 |       spawn do
363 |         3.times { |i| nats.publish write_subject, i.to_s }
364 |         nats.flush
365 |       end
366 | 
367 |       if msg = pull.fetch(timeout: 1.second)
368 |         msg.subject.should eq write_subject
369 |         msg.body.should eq "0".to_slice
370 | 
371 |         nats.jetstream.ack msg
372 |       else
373 |         raise "Did not receive a message within 2 seconds"
374 |       end
375 | 
376 |       msgs = pull.fetch(3, timeout: 100.milliseconds)
377 |       msgs.map(&.body).should eq [
378 |         "1".to_slice,
379 |         "2".to_slice,
380 |       ]
381 | 
382 |       msgs.each { |msg| nats.jetstream.ack msg }
383 |       nats.flush
384 |       consumer = nats
385 |         .jetstream
386 |         .consumer
387 |         .info(stream_name: stream.config.name, name: consumer_name)
388 |         .not_nil!
389 |       consumer.num_waiting.should eq 0
390 |     ensure
391 |       nats.jetstream.stream.delete stream
392 |     end
393 |   end
394 | 
395 |   it "reads from ephemeral pull consumers" do
396 |     write_subject = UUID.random.to_s
397 |     consumer_name = UUID.random.to_s
398 |     stream = create_stream([write_subject])
399 |     consumer = nats.jetstream.consumer.create(
400 |       stream_name: stream.config.name,
401 |       max_deliver: -1
402 |     )
403 |     pull = nats.jetstream.pull_subscribe(consumer)
404 | 
405 |     begin
406 |       3.times { |i| nats.publish write_subject, i.to_s }
407 | 
408 |       if msg = pull.fetch(timeout: 100.milliseconds)
409 |         msg.subject.should eq write_subject
410 |         msg.body.should eq "0".to_slice
411 |       else
412 |         raise "Did not receive a message within 500ms"
413 |       end
414 | 
415 |       msgs = pull.fetch(3, timeout: 100.milliseconds)
416 |       msgs.map(&.body).should eq [
417 |         "1".to_slice,
418 |         "2".to_slice,
419 |       ]
420 |     ensure
421 |       nats.jetstream.stream.delete stream
422 |     end
423 |   end
424 | 
425 |   describe "counters" do
426 |     test "increments and checks", stream_options: {allow_msg_counter: true} do
427 |       # Incrementing returns the value
428 |       js.publish(write_subject, "", headers: NATS::Headers{"Nats-Incr" => "+1"})
429 |         .as(NATS::JetStream::PubAck)
430 |         .val.not_nil!
431 |         .to_i64
432 |         .should eq 1
433 |       js.publish(write_subject, "", headers: NATS::Headers{"Nats-Incr" => "+4"})
434 |         .as(NATS::JetStream::PubAck)
435 |         .val.not_nil!
436 |         .to_i64
437 |         .should eq 5
438 | 
439 |       # Fetching the current value
440 |       unless response = js.stream.get_msg(stream.config.name, last_by_subject: write_subject)
441 |         raise "Didn't get a response from NATS JetStream"
442 |       end
443 |       CounterResponse.from_json(response.message.data_string).value.should eq 5
444 |     end
445 |   end
446 | 
447 |   describe "compression" do
448 |     test "creates streams with S2 compression", stream_options: {compression: :s2} do
449 |       stream.config.compression.s2?.should eq true
450 |     end
451 | 
452 |     test "creates streams with no compression", stream_options: {compression: :none} do
453 |       stream.config.compression.none?.should eq true
454 |     end
455 |   end
456 | 
457 |   describe "purging a stream" do
458 |     it "purges by subject" do
459 |       first, second = Array.new(2) { UUID.random.to_s }
460 |       stream = create_stream(subjects: [first, second])
461 |       name = stream.config.name
462 | 
463 |       js.publish first, "test"
464 |       js.publish first, "another test"
465 |       js.publish second, "yet another"
466 | 
467 |       js.stream.get_msg(name, sequence: 1).not_nil!.message.data.should eq "test".to_slice
468 |       js.stream.get_msg(name, sequence: 2).not_nil!.message.data.should eq "another test".to_slice
469 |       js.stream.get_msg(name, sequence: 3).not_nil!.message.data.should eq "yet another".to_slice
470 | 
471 |       js.stream.purge name, subject: first
472 | 
473 |       js.stream.info(name).not_nil!.state.messages.should eq 1
474 |     ensure
475 |       js.stream.delete stream if stream
476 |     end
477 |   end
478 | end
479 | 


--------------------------------------------------------------------------------
/docs/css/style.css:
--------------------------------------------------------------------------------
  1 | :root {
  2 |   color-scheme: light dark;
  3 | }
  4 | 
  5 | html, body {
  6 |   background: #FFFFFF;
  7 |   position: relative;
  8 |   margin: 0;
  9 |   padding: 0;
 10 |   width: 100%;
 11 |   height: 100%;
 12 |   overflow: hidden;
 13 | }
 14 | 
 15 | body {
 16 |   font-family: "Avenir", "Tahoma", "Lucida Sans", "Lucida Grande", Verdana, Arial, sans-serif;
 17 |   color: #333;
 18 |   line-height: 1.5;
 19 | }
 20 | 
 21 | a {
 22 |   color: #263F6C;
 23 | }
 24 | 
 25 | a:visited {
 26 |   color: #112750;
 27 | }
 28 | 
 29 | h1, h2, h3, h4, h5, h6 {
 30 |   margin: 35px 0 25px;
 31 |   color: #444444;
 32 | }
 33 | 
 34 | h1.type-name {
 35 |   color: #47266E;
 36 |   margin: 20px 0 30px;
 37 |   background-color: #F8F8F8;
 38 |   padding: 10px 12px;
 39 |   border: 1px solid #EBEBEB;
 40 |   border-radius: 2px;
 41 | }
 42 | 
 43 | h2 {
 44 |   border-bottom: 1px solid #E6E6E6;
 45 |   padding-bottom: 5px;
 46 | }
 47 | 
 48 | body {
 49 |   display: flex;
 50 | }
 51 | 
 52 | .sidebar, .main-content {
 53 |   overflow: auto;
 54 | }
 55 | 
 56 | p, li {
 57 |   max-width: 42em;
 58 | }
 59 | 
 60 | .methods-inherited {
 61 |   max-width: 60em;
 62 | }
 63 | 
 64 | .sidebar {
 65 |   width: 30em;
 66 |   color: #F8F4FD;
 67 |   background-color: #2E1052;
 68 |   padding: 0 0 30px;
 69 |   box-shadow: inset -3px 0 4px rgba(0,0,0,.35);
 70 |   line-height: 1.2;
 71 |   z-index: 0;
 72 | }
 73 | 
 74 | .sidebar .search-box {
 75 |   padding: 13px 9px;
 76 | }
 77 | 
 78 | .sidebar input {
 79 |   display: block;
 80 |   box-sizing: border-box;
 81 |   margin: 0;
 82 |   padding: 5px;
 83 |   font: inherit;
 84 |   font-family: inherit;
 85 |   line-height: 1.2;
 86 |   width: 100%;
 87 |   border: 0;
 88 |   outline: 0;
 89 |   border-radius: 2px;
 90 |   box-shadow: 0px 3px 5px rgba(0,0,0,.25);
 91 |   transition: box-shadow .12s;
 92 | }
 93 | 
 94 | .sidebar input:focus {
 95 |   box-shadow: 0px 5px 6px rgba(0,0,0,.5);
 96 | }
 97 | 
 98 | .sidebar input::-webkit-input-placeholder { /* Chrome/Opera/Safari */
 99 |   color: #757575;
100 |   font-size: 14px;
101 |   text-indent: 2px;
102 | }
103 | 
104 | .sidebar input::-moz-placeholder { /* Firefox 19+ */
105 |   color: #757575;
106 |   font-size: 14px;
107 |   text-indent: 2px;
108 | }
109 | 
110 | .sidebar input:-ms-input-placeholder { /* IE 10+ */
111 |   color: #757575;
112 |   font-size: 14px;
113 |   text-indent: 2px;
114 | }
115 | 
116 | .sidebar input:-moz-placeholder { /* Firefox 18- */
117 |   color: #757575;
118 |   font-size: 14px;
119 |   text-indent: 2px;
120 | }
121 | 
122 | .project-summary {
123 |   padding: 9px 15px 30px 30px;
124 | }
125 | 
126 | .project-name {
127 |   font-size: 1.4rem;
128 |   margin: 0;
129 |   color: #f4f4f4;
130 |   font-weight: 600;
131 | }
132 | 
133 | .project-version {
134 |   margin-top: 5px;
135 |   display: inline-block;
136 |   position: relative;
137 | }
138 | 
139 | .project-version > form::after {
140 |   position: absolute;
141 |   right: 0;
142 |   top: 0;
143 |   content: "\25BC";
144 |   font-size: .6em;
145 |   line-height: 1.2rem;
146 |   z-index: -1;
147 | }
148 | 
149 | .project-versions-nav {
150 |   cursor: pointer;
151 |   margin: 0;
152 |   padding: 0 .9em 0 0;
153 |   border: none;
154 |   -moz-appearance: none;
155 |   -webkit-appearance: none;
156 |   appearance: none;
157 |   background-color: transparent;
158 |   color: inherit;
159 |   font-family: inherit;
160 |   font-size: inherit;
161 |   line-height: inherit;
162 | }
163 | .project-versions-nav:focus {
164 |   outline: none;
165 | }
166 | 
167 | .project-versions-nav > option {
168 |   color: initial;
169 | }
170 | 
171 | .sidebar ul {
172 |   margin: 0;
173 |   padding: 0;
174 |   list-style: none outside;
175 | }
176 | 
177 | .sidebar li {
178 |   display: block;
179 |   position: relative;
180 | }
181 | 
182 | .types-list li.hide {
183 |   display: none;
184 | }
185 | 
186 | .sidebar a {
187 |   text-decoration: none;
188 |   color: inherit;
189 |   transition: color .14s;
190 | }
191 | .types-list a {
192 |   display: block;
193 |   padding: 5px 15px 5px 30px;
194 | }
195 | 
196 | .types-list {
197 |   display: block;
198 | }
199 | 
200 | .sidebar a:focus {
201 |   outline: 1px solid #D1B7F1;
202 | }
203 | 
204 | .types-list a {
205 |   padding: 5px 15px 5px 30px;
206 | }
207 | 
208 | .sidebar .current > a,
209 | .sidebar a:hover {
210 |   color: #866BA6;
211 | }
212 | 
213 | .types-list li ul {
214 |   overflow: hidden;
215 |   height: 0;
216 |   max-height: 0;
217 |   transition: 1s ease-in-out;
218 | }
219 | 
220 | .types-list li.parent {
221 |   padding-left: 30px;
222 | }
223 | 
224 | .types-list li.parent::before {
225 |   box-sizing: border-box;
226 |   content: "▼";
227 |   display: block;
228 |   width: 30px;
229 |   height: 30px;
230 |   position: absolute;
231 |   top: 0;
232 |   left: 0;
233 |   text-align: center;
234 |   color: white;
235 |   font-size: 8px;
236 |   line-height: 30px;
237 |   transform: rotateZ(-90deg);
238 |   cursor: pointer;
239 |   transition: .2s linear;
240 | }
241 | 
242 | 
243 | .types-list li.parent > a {
244 |   padding-left: 0;
245 | }
246 | 
247 | .types-list li.parent.open::before {
248 |   transform: rotateZ(0);
249 | }
250 | 
251 | .types-list li.open > ul {
252 |   height: auto;
253 |   max-height: 1000em;
254 | }
255 | 
256 | .main-content {
257 |   padding: 0 30px 30px 30px;
258 |   width: 100%;
259 | }
260 | 
261 | .kind {
262 |   font-size: 60%;
263 |   color: #866BA6;
264 | }
265 | 
266 | .superclass-hierarchy {
267 |   margin: -15px 0 30px 0;
268 |   padding: 0;
269 |   list-style: none outside;
270 |   font-size: 80%;
271 | }
272 | 
273 | .superclass-hierarchy .superclass {
274 |   display: inline-block;
275 |   margin: 0 7px 0 0;
276 |   padding: 0;
277 | }
278 | 
279 | .superclass-hierarchy .superclass + .superclass::before {
280 |   content: "<";
281 |   margin-right: 7px;
282 | }
283 | 
284 | .other-types-list li {
285 |   display: inline-block;
286 | }
287 | 
288 | .other-types-list,
289 | .list-summary {
290 |   margin: 0 0 30px 0;
291 |   padding: 0;
292 |   list-style: none outside;
293 | }
294 | 
295 | .entry-const {
296 |   font-family: Menlo, Monaco, Consolas, 'Courier New', Courier, monospace;
297 | }
298 | 
299 | .entry-const code {
300 |   white-space: pre-wrap;
301 | }
302 | 
303 | .entry-summary {
304 |   padding-bottom: 4px;
305 | }
306 | 
307 | .superclass-hierarchy .superclass a,
308 | .other-type a,
309 | .entry-summary .signature {
310 |   padding: 4px 8px;
311 |   margin-bottom: 4px;
312 |   display: inline-block;
313 |   background-color: #f8f8f8;
314 |   color: #47266E;
315 |   border: 1px solid #f0f0f0;
316 |   text-decoration: none;
317 |   border-radius: 3px;
318 |   font-family: Menlo, Monaco, Consolas, 'Courier New', Courier, monospace;
319 |   transition: background .15s, border-color .15s;
320 | }
321 | 
322 | .superclass-hierarchy .superclass a:hover,
323 | .other-type a:hover,
324 | .entry-summary .signature:hover {
325 |   background: #D5CAE3;
326 |   border-color: #624288;
327 | }
328 | 
329 | .entry-summary .summary {
330 |   padding-left: 32px;
331 | }
332 | 
333 | .entry-summary .summary p {
334 |   margin: 12px 0 16px;
335 | }
336 | 
337 | .entry-summary a {
338 |   text-decoration: none;
339 | }
340 | 
341 | .entry-detail {
342 |   padding: 30px 0;
343 | }
344 | 
345 | .entry-detail .signature {
346 |   position: relative;
347 |   padding: 5px 15px;
348 |   margin-bottom: 10px;
349 |   display: block;
350 |   border-radius: 5px;
351 |   background-color: #f8f8f8;
352 |   color: #47266E;
353 |   border: 1px solid #f0f0f0;
354 |   font-family: Menlo, Monaco, Consolas, 'Courier New', Courier, monospace;
355 |   transition: .2s ease-in-out;
356 | }
357 | 
358 | .entry-detail:target .signature {
359 |   background-color: #D5CAE3;
360 |   border: 1px solid #624288;
361 | }
362 | 
363 | .entry-detail .signature .method-permalink {
364 |   position: absolute;
365 |   top: 0;
366 |   left: -35px;
367 |   padding: 5px 15px;
368 |   text-decoration: none;
369 |   font-weight: bold;
370 |   color: #624288;
371 |   opacity: .4;
372 |   transition: opacity .2s;
373 | }
374 | 
375 | .entry-detail .signature .method-permalink:hover {
376 |   opacity: 1;
377 | }
378 | 
379 | .entry-detail:target .signature .method-permalink {
380 |   opacity: 1;
381 | }
382 | 
383 | .methods-inherited {
384 |   padding-right: 10%;
385 |   line-height: 1.5em;
386 | }
387 | 
388 | .methods-inherited h3 {
389 |   margin-bottom: 4px;
390 | }
391 | 
392 | .methods-inherited a {
393 |   display: inline-block;
394 |   text-decoration: none;
395 |   color: #47266E;
396 | }
397 | 
398 | .methods-inherited a:hover {
399 |   text-decoration: underline;
400 |   color: #6C518B;
401 | }
402 | 
403 | .methods-inherited .tooltip>span {
404 |   background: #D5CAE3;
405 |   padding: 4px 8px;
406 |   border-radius: 3px;
407 |   margin: -4px -8px;
408 | }
409 | 
410 | .methods-inherited .tooltip * {
411 |   color: #47266E;
412 | }
413 | 
414 | pre {
415 |   padding: 10px 20px;
416 |   margin-top: 4px;
417 |   border-radius: 3px;
418 |   line-height: 1.45;
419 |   overflow: auto;
420 |   color: #333;
421 |   background: #fdfdfd;
422 |   font-size: 14px;
423 |   border: 1px solid #eee;
424 | }
425 | 
426 | code {
427 |   font-family: Menlo, Monaco, Consolas, 'Courier New', Courier, monospace;
428 | }
429 | 
430 | :not(pre) > code {
431 |   background-color: rgba(40,35,30,0.05);
432 |   padding: 0.2em 0.4em;
433 |   font-size: 85%;
434 |   border-radius: 3px;
435 | }
436 | 
437 | span.flag {
438 |   padding: 2px 4px 1px;
439 |   border-radius: 3px;
440 |   margin-right: 3px;
441 |   font-size: 11px;
442 |   border: 1px solid transparent;
443 | }
444 | 
445 | span.flag.orange {
446 |   background-color: #EE8737;
447 |   color: #FCEBDD;
448 |   border-color: #EB7317;
449 | }
450 | 
451 | span.flag.yellow {
452 |   background-color: #E4B91C;
453 |   color: #FCF8E8;
454 |   border-color: #B69115;
455 | }
456 | 
457 | span.flag.green {
458 |   background-color: #469C14;
459 |   color: #E2F9D3;
460 |   border-color: #34700E;
461 | }
462 | 
463 | span.flag.red {
464 |   background-color: #BF1919;
465 |   color: #F9ECEC;
466 |   border-color: #822C2C;
467 | }
468 | 
469 | span.flag.purple {
470 |   background-color: #2E1052;
471 |   color: #ECE1F9;
472 |   border-color: #1F0B37;
473 | }
474 | 
475 | span.flag.lime {
476 |   background-color: #a3ff00;
477 |   color: #222222;
478 |   border-color: #00ff1e;
479 | }
480 | 
481 | .tooltip>span {
482 |   position: absolute;
483 |   opacity: 0;
484 |   display: none;
485 |   pointer-events: none;
486 | }
487 | 
488 | .tooltip:hover>span {
489 |   display: inline-block;
490 |   opacity: 1;
491 | }
492 | 
493 | .c {
494 |   color: #969896;
495 | }
496 | 
497 | .n {
498 |   color: #0086b3;
499 | }
500 | 
501 | .t {
502 |   color: #0086b3;
503 | }
504 | 
505 | .s {
506 |   color: #183691;
507 | }
508 | 
509 | .i {
510 |   color: #7f5030;
511 | }
512 | 
513 | .k {
514 |   color: #a71d5d;
515 | }
516 | 
517 | .o {
518 |   color: #a71d5d;
519 | }
520 | 
521 | .m {
522 |   color: #795da3;
523 | }
524 | 
525 | .hidden {
526 |   display: none;
527 | }
528 | .search-results {
529 |   font-size: 90%;
530 |   line-height: 1.3;
531 | }
532 | 
533 | .search-results mark {
534 |   color: inherit;
535 |   background: transparent;
536 |   font-weight: bold;
537 | }
538 | .search-result {
539 |   padding: 5px 8px 5px 5px;
540 |   cursor: pointer;
541 |   border-left: 5px solid transparent;
542 |   transform: translateX(-3px);
543 |   transition: all .2s, background-color 0s, border .02s;
544 |   min-height: 3.2em;
545 | }
546 | .search-result.current {
547 |   border-left-color: #ddd;
548 |   background-color: rgba(200,200,200,0.4);
549 |   transform: translateX(0);
550 |   transition: all .2s, background-color .5s, border 0s;
551 | }
552 | .search-result.current:hover,
553 | .search-result.current:focus {
554 |   border-left-color: #866BA6;
555 | }
556 | .search-result:not(.current):nth-child(2n) {
557 |   background-color: rgba(255,255,255,.06);
558 | }
559 | .search-result__title {
560 |   font-size: 105%;
561 |   word-break: break-all;
562 |   line-height: 1.1;
563 |   padding: 3px 0;
564 | }
565 | .search-result__title strong {
566 |   font-weight: normal;
567 | }
568 | .search-results .search-result__title > a {
569 |   padding: 0;
570 |   display: block;
571 | }
572 | .search-result__title > a > .args {
573 |   color: #dddddd;
574 |   font-weight: 300;
575 |   transition: inherit;
576 |   font-size: 88%;
577 |   line-height: 1.2;
578 |   letter-spacing: -.02em;
579 | }
580 | .search-result__title > a > .args * {
581 |   color: inherit;
582 | }
583 | 
584 | .search-result a,
585 | .search-result a:hover {
586 |   color: inherit;
587 | }
588 | .search-result:not(.current):hover .search-result__title > a,
589 | .search-result:not(.current):focus .search-result__title > a,
590 | .search-result__title > a:focus {
591 |   color: #866BA6;
592 | }
593 | .search-result:not(.current):hover .args,
594 | .search-result:not(.current):focus .args {
595 |   color: #6a5a7d;
596 | }
597 | 
598 | .search-result__type {
599 |   color: #e8e8e8;
600 |   font-weight: 300;
601 | }
602 | .search-result__doc {
603 |   color: #bbbbbb;
604 |   font-size: 90%;
605 | }
606 | .search-result__doc p {
607 |   margin: 0;
608 |   text-overflow: ellipsis;
609 |   display: -webkit-box;
610 |   -webkit-box-orient: vertical;
611 |   -webkit-line-clamp: 2;
612 |   overflow: hidden;
613 |   line-height: 1.2em;
614 |   max-height: 2.4em;
615 | }
616 | 
617 | .js-modal-visible .modal-background {
618 |   display: flex;
619 | }
620 | .main-content {
621 |   position: relative;
622 | }
623 | .modal-background {
624 |   position: absolute;
625 |   display: none;
626 |   height: 100%;
627 |   width: 100%;
628 |   background: rgba(120,120,120,.4);
629 |   z-index: 100;
630 |   align-items: center;
631 |   justify-content: center;
632 | }
633 | .usage-modal {
634 |   max-width: 90%;
635 |   background: #fff;
636 |   border: 2px solid #ccc;
637 |   border-radius: 9px;
638 |   padding: 5px 15px 20px;
639 |   min-width: 50%;
640 |   color: #555;
641 |   position: relative;
642 |   transform: scale(.5);
643 |   transition: transform 200ms;
644 | }
645 | .js-modal-visible .usage-modal {
646 |   transform: scale(1);
647 | }
648 | .usage-modal > .close-button {
649 |   position: absolute;
650 |   right: 15px;
651 |   top: 8px;
652 |   color: #aaa;
653 |   font-size: 27px;
654 |   cursor: pointer;
655 | }
656 | .usage-modal > .close-button:hover {
657 |   text-shadow: 2px 2px 2px #ccc;
658 |   color: #999;
659 | }
660 | .modal-title {
661 |   margin: 0;
662 |   text-align: center;
663 |   font-weight: normal;
664 |   color: #666;
665 |   border-bottom: 2px solid #ddd;
666 |   padding: 10px;
667 | }
668 | .usage-list {
669 |   padding: 0;
670 |   margin: 13px;
671 | }
672 | .usage-list > li {
673 |   padding: 5px 2px;
674 |   overflow: auto;
675 |   padding-left: 100px;
676 |   min-width: 12em;
677 | }
678 | .usage-modal kbd {
679 |   background: #eee;
680 |   border: 1px solid #ccc;
681 |   border-bottom-width: 2px;
682 |   border-radius: 3px;
683 |   padding: 3px 8px;
684 |   font-family: monospace;
685 |   margin-right: 2px;
686 |   display: inline-block;
687 | }
688 | .usage-key {
689 |   float: left;
690 |   clear: left;
691 |   margin-left: -100px;
692 |   margin-right: 12px;
693 | }
694 | .doc-inherited {
695 |   font-weight: bold;
696 | }
697 | 
698 | .anchor {
699 |   float: left;
700 |   padding-right: 4px;
701 |   margin-left: -20px;
702 | }
703 | 
704 | .main-content .anchor .octicon-link {
705 |   width: 16px;
706 |   height: 16px;
707 | }
708 | 
709 | .main-content .anchor:focus {
710 |   outline: none
711 | }
712 | 
713 | .main-content h1:hover .anchor,
714 | .main-content h2:hover .anchor,
715 | .main-content h3:hover .anchor,
716 | .main-content h4:hover .anchor,
717 | .main-content h5:hover .anchor,
718 | .main-content h6:hover .anchor {
719 |   text-decoration: none
720 | }
721 | 
722 | .main-content h1 .octicon-link,
723 | .main-content h2 .octicon-link,
724 | .main-content h3 .octicon-link,
725 | .main-content h4 .octicon-link,
726 | .main-content h5 .octicon-link,
727 | .main-content h6 .octicon-link {
728 |   visibility: hidden
729 | }
730 | 
731 | .main-content h1:hover .anchor .octicon-link,
732 | .main-content h2:hover .anchor .octicon-link,
733 | .main-content h3:hover .anchor .octicon-link,
734 | .main-content h4:hover .anchor .octicon-link,
735 | .main-content h5:hover .anchor .octicon-link,
736 | .main-content h6:hover .anchor .octicon-link {
737 |   visibility: visible
738 | }
739 | 
740 | img {
741 |   max-width: 100%;
742 | }
743 | 
744 | table {
745 |   font-size: 14px;
746 |   display: block;
747 |   max-width: -moz-fit-content;
748 |   max-width: fit-content;
749 |   overflow-x: auto;
750 |   white-space: nowrap;
751 |   background: #fdfdfd;
752 |   text-align: center;
753 |   border: 1px solid #eee;
754 |   border-collapse: collapse;
755 |   padding: 0px 5px 0px 5px;
756 | }
757 | 
758 | table th {
759 |   padding: 10px;
760 |   letter-spacing: 1px;
761 |   border-bottom: 1px solid #eee;
762 | }
763 | 
764 | table td {
765 |   padding: 10px;
766 | }
767 | 
768 | #sidebar-btn {
769 |   height: 32px;
770 |   width: 32px;
771 | }
772 | 
773 | #sidebar-btn-label {
774 |   height: 2em;
775 |   width: 2em;
776 | }
777 | 
778 | #sidebar-btn, #sidebar-btn-label {
779 |   display: none;
780 |   margin: .7rem;
781 |   appearance: none;
782 |   color: black;
783 |   cursor: pointer;
784 | }
785 | 
786 | @media only screen and (max-width: 635px) {
787 |   .sidebar, .main-content {
788 |     /* svg size + vertical margin - .search-box padding-top */
789 |     padding-top: calc(2em + 2 * 0.7rem - 13px);
790 |   }
791 | 
792 |   #sidebar-btn, #sidebar-btn-label {
793 |     display: block;
794 |     position: absolute;
795 |     z-index: 50;
796 |     transition-duration: 200ms;
797 |     left: 0;
798 |   }
799 |   
800 |   #sidebar-btn:not(:checked) ~ #sidebar-btn-label > .close,
801 |   #sidebar-btn:checked ~ #sidebar-btn-label > .open,
802 |   #sidebar-btn:checked ~ .main-content {
803 |     display: none;
804 |   }
805 | 
806 |   #sidebar-btn:checked {
807 |     left: calc(100% - 32px - (2 * 0.7rem));
808 |   }
809 | 
810 |   #sidebar-btn:checked ~ #sidebar-btn-label {
811 |     color: white;
812 |     /* 100% - svg size - horizontal margin */
813 |     left: calc(100% - 2em - (2 * 0.7rem));
814 |   }
815 | 
816 |   #sidebar-btn~.sidebar {
817 |     width: 0%;
818 |   }
819 | 
820 |   #sidebar-btn:checked~.sidebar {
821 |     visibility: visible;
822 |     width: 100%;
823 |   }
824 | 
825 |   .sidebar {
826 |     transition-duration: 200ms;
827 |     max-width: 100vw;
828 |     visibility: hidden;
829 |   }
830 | }
831 | 
832 | @media (prefers-color-scheme: dark) {
833 |   html, body {
834 |     background: #1b1b1b;
835 |   }
836 | 
837 |   body {
838 |     color: white;
839 |   }
840 | 
841 |   a {
842 |     color: #8cb4ff;
843 |   }
844 | 
845 |   .main-content a:visited {
846 |     color: #5f8de3;
847 |   }
848 | 
849 |   h1, h2, h3, h4, h5, h6 {
850 |     color: white;
851 |   }
852 | 
853 |   h1.type-name {
854 |     color: white;
855 |     background-color: #202020;
856 |     border: 1px solid #353535;
857 |   }
858 | 
859 |   .project-versions-nav > option {
860 |     background-color: #222;
861 |   }
862 | 
863 |   .superclass-hierarchy .superclass a,
864 |   .superclass-hierarchy .superclass a:visited,
865 |   .other-type a,
866 |   .other-type a:visited,
867 |   .entry-summary .signature,
868 |   .entry-summary a:visited {
869 |     background-color: #202020;
870 |     color: white;
871 |     border: 1px solid #353535;
872 |   }
873 | 
874 |   .superclass-hierarchy .superclass a:hover,
875 |   .other-type a:hover,
876 |   .entry-summary .signature:hover {
877 |     background: #443d4d;
878 |     border-color: #b092d4;
879 |   }
880 | 
881 |   .kind {
882 |     color: #b092d4;
883 |   }
884 | 
885 |   .n {
886 |     color: #00ade6;
887 |   }
888 | 
889 |   .t {
890 |     color: #00ade6;
891 |   }
892 | 
893 |   .k {
894 |     color: #ff66ae;
895 |   }
896 | 
897 |   .o {
898 |     color: #ff66ae;
899 |   }
900 | 
901 |   .s {
902 |     color: #7799ff;
903 |   }
904 | 
905 |   .i {
906 |     color: #b38668;
907 |   }
908 | 
909 |   .m {
910 |     color: #b9a5d6;
911 |   }
912 | 
913 |   .c {
914 |     color: #a1a1a1;
915 |   }
916 | 
917 |   .methods-inherited a, .methods-inherited a:visited {
918 |     color: #B290D9;
919 |   }
920 | 
921 |   .methods-inherited a:hover {
922 |     color: #D4B7F4;
923 |   }
924 | 
925 |   .methods-inherited .tooltip>span {
926 |     background: #443d4d;
927 |   }
928 | 
929 |   .methods-inherited .tooltip * {
930 |     color: white;
931 |   }
932 | 
933 |   .entry-detail:target .signature {
934 |     background-color: #443d4d;
935 |     border: 1px solid #b092d4;
936 |   }
937 | 
938 |   .entry-detail .signature {
939 |     background-color: #202020;
940 |     color: white;
941 |     border: 1px solid #353535;
942 |   }
943 | 
944 |   .entry-detail .signature .method-permalink {
945 |     color: #b092d4;
946 |   }
947 | 
948 |   :not(pre)>code {
949 |     background-color: #202020;
950 |   }
951 | 
952 |   span.flag.purple {
953 |     background-color: #443d4d;
954 |     color: #ECE1F9;
955 |     border-color: #b092d4;
956 |   }
957 | 
958 |   .sidebar input::-webkit-input-placeholder { /* Chrome/Opera/Safari */
959 |     color: white;
960 |   }
961 |   
962 |   .sidebar input::-moz-placeholder { /* Firefox 19+ */
963 |     color: white;
964 |   }
965 |   
966 |   .sidebar input:-ms-input-placeholder { /* IE 10+ */
967 |     color: white;
968 |   }
969 |   
970 |   .sidebar input:-moz-placeholder { /* Firefox 18- */
971 |     color: white;
972 |   }
973 | 
974 |   pre,
975 |   table {
976 |     color: white;
977 |     background: #202020;
978 |     border: 1px solid #353535;
979 |   }
980 | 
981 |   table th {
982 |     border-bottom: 1px solid #353535;
983 |   }
984 | 
985 |   #sidebar-btn, #sidebar-btn-label {
986 |     color: white;
987 |   }
988 | }
989 | 


--------------------------------------------------------------------------------
/docs/NATS/JetStream/Placement.html:
--------------------------------------------------------------------------------
  1 | <!DOCTYPE html>
  2 | <html lang="en">
  3 | <head>
  4 |   <meta charset="utf-8" />
  5 | <meta http-equiv="X-UA-Compatible" content="IE=edge">
  6 | <meta name="generator" content="Crystal Docs 1.5.1">
  7 | <meta name="crystal_docs.project_version" content="1.2.3">
  8 | <meta name="crystal_docs.project_name" content="nats">
  9 | 
 10 | 
 11 | 
 12 | <link href="../../css/style.css" rel="stylesheet" type="text/css" />
 13 | <script type="text/javascript" src="../../js/doc.js"></script>
 14 | 
 15 |   <meta name="repository-name" content="nats">
 16 |   <title>NATS::JetStream::Placement - nats 1.2.3</title>
 17 |   <script type="text/javascript">
 18 |     CrystalDocs.base_path = "../../";
 19 |   </script>
 20 | </head>
 21 | <body>
 22 | 
 23 | <svg class="hidden">
 24 |   <symbol id="octicon-link" viewBox="0 0 16 16">
 25 |     <path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path>
 26 |   </symbol>
 27 | </svg>
 28 | <div class="sidebar">
 29 |   <div class="sidebar-header">
 30 |     <div class="search-box">
 31 |       <input type="search" class="search-input" placeholder="Search..." spellcheck="false" aria-label="Search">
 32 |     </div>
 33 | 
 34 |     <div class="project-summary">
 35 |       <h1 class="project-name">
 36 |         <a href="../../index.html">
 37 |           nats
 38 |         </a>
 39 |       </h1>
 40 | 
 41 |       <span class="project-version">
 42 |         1.2.3
 43 |       </span>
 44 |     </div>
 45 |   </div>
 46 | 
 47 |   <div class="search-results hidden">
 48 |     <ul class="search-list"></ul>
 49 |   </div>
 50 | 
 51 |   <div class="types-list">
 52 |     <ul>
 53 |   
 54 |   <li class="parent open current" data-id="nats/NATS" data-name="nats">
 55 |       <a href="../../NATS.html">NATS</a>
 56 |       
 57 |         <ul>
 58 |   
 59 |   <li class="parent " data-id="nats/NATS/Client" data-name="nats::client">
 60 |       <a href="../../NATS/Client.html">Client</a>
 61 |       
 62 |         <ul>
 63 |   
 64 |   <li class=" " data-id="nats/NATS/Client/ClientClosed" data-name="nats::client::clientclosed">
 65 |       <a href="../../NATS/Client/ClientClosed.html">ClientClosed</a>
 66 |       
 67 |     </li>
 68 |   
 69 |   <li class=" " data-id="nats/NATS/Client/Data" data-name="nats::client::data">
 70 |       <a href="../../NATS/Client/Data.html">Data</a>
 71 |       
 72 |     </li>
 73 |   
 74 |   <li class=" " data-id="nats/NATS/Client/State" data-name="nats::client::state">
 75 |       <a href="../../NATS/Client/State.html">State</a>
 76 |       
 77 |     </li>
 78 |   
 79 | </ul>
 80 | 
 81 |       
 82 |     </li>
 83 |   
 84 |   <li class=" " data-id="nats/NATS/Data" data-name="nats::data">
 85 |       <a href="../../NATS/Data.html">Data</a>
 86 |       
 87 |     </li>
 88 |   
 89 |   <li class=" " data-id="nats/NATS/Error" data-name="nats::error">
 90 |       <a href="../../NATS/Error.html">Error</a>
 91 |       
 92 |     </li>
 93 |   
 94 |   <li class=" " data-id="nats/NATS/Headers" data-name="nats::headers">
 95 |       <a href="../../NATS/Headers.html">Headers</a>
 96 |       
 97 |     </li>
 98 |   
 99 |   <li class="parent open current" data-id="nats/NATS/JetStream" data-name="nats::jetstream">
100 |       <a href="../../NATS/JetStream.html">JetStream</a>
101 |       
102 |         <ul>
103 |   
104 |   <li class="parent " data-id="nats/NATS/JetStream/API" data-name="nats::jetstream::api">
105 |       <a href="../../NATS/JetStream/API.html">API</a>
106 |       
107 |         <ul>
108 |   
109 |   <li class=" " data-id="nats/NATS/JetStream/API/Message" data-name="nats::jetstream::api::message">
110 |       <a href="../../NATS/JetStream/API/Message.html">Message</a>
111 |       
112 |     </li>
113 |   
114 |   <li class="parent " data-id="nats/NATS/JetStream/API/V1" data-name="nats::jetstream::api::v1">
115 |       <a href="../../NATS/JetStream/API/V1.html">V1</a>
116 |       
117 |         <ul>
118 |   
119 |   <li class=" " data-id="nats/NATS/JetStream/API/V1/APIError" data-name="nats::jetstream::api::v1::apierror">
120 |       <a href="../../NATS/JetStream/API/V1/APIError.html">APIError</a>
121 |       
122 |     </li>
123 |   
124 |   <li class=" " data-id="nats/NATS/JetStream/API/V1/ClusterInfo" data-name="nats::jetstream::api::v1::clusterinfo">
125 |       <a href="../../NATS/JetStream/API/V1/ClusterInfo.html">ClusterInfo</a>
126 |       
127 |     </li>
128 |   
129 |   <li class="parent " data-id="nats/NATS/JetStream/API/V1/Consumer" data-name="nats::jetstream::api::v1::consumer">
130 |       <a href="../../NATS/JetStream/API/V1/Consumer.html">Consumer</a>
131 |       
132 |         <ul>
133 |   
134 |   <li class=" " data-id="nats/NATS/JetStream/API/V1/Consumer/Sequence" data-name="nats::jetstream::api::v1::consumer::sequence">
135 |       <a href="../../NATS/JetStream/API/V1/Consumer/Sequence.html">Sequence</a>
136 |       
137 |     </li>
138 |   
139 | </ul>
140 | 
141 |       
142 |     </li>
143 |   
144 |   <li class="parent " data-id="nats/NATS/JetStream/API/V1/ConsumerConfig" data-name="nats::jetstream::api::v1::consumerconfig">
145 |       <a href="../../NATS/JetStream/API/V1/ConsumerConfig.html">ConsumerConfig</a>
146 |       
147 |         <ul>
148 |   
149 |   <li class=" " data-id="nats/NATS/JetStream/API/V1/ConsumerConfig/AckPolicy" data-name="nats::jetstream::api::v1::consumerconfig::ackpolicy">
150 |       <a href="../../NATS/JetStream/API/V1/ConsumerConfig/AckPolicy.html">AckPolicy</a>
151 |       
152 |     </li>
153 |   
154 |   <li class=" " data-id="nats/NATS/JetStream/API/V1/ConsumerConfig/DeliverPolicy" data-name="nats::jetstream::api::v1::consumerconfig::deliverpolicy">
155 |       <a href="../../NATS/JetStream/API/V1/ConsumerConfig/DeliverPolicy.html">DeliverPolicy</a>
156 |       
157 |     </li>
158 |   
159 |   <li class=" " data-id="nats/NATS/JetStream/API/V1/ConsumerConfig/ReplayPolicy" data-name="nats::jetstream::api::v1::consumerconfig::replaypolicy">
160 |       <a href="../../NATS/JetStream/API/V1/ConsumerConfig/ReplayPolicy.html">ReplayPolicy</a>
161 |       
162 |     </li>
163 |   
164 | </ul>
165 | 
166 |       
167 |     </li>
168 |   
169 |   <li class=" " data-id="nats/NATS/JetStream/API/V1/ConsumerListResponse" data-name="nats::jetstream::api::v1::consumerlistresponse">
170 |       <a href="../../NATS/JetStream/API/V1/ConsumerListResponse.html">ConsumerListResponse</a>
171 |       
172 |     </li>
173 |   
174 |   <li class=" " data-id="nats/NATS/JetStream/API/V1/Consumers" data-name="nats::jetstream::api::v1::consumers">
175 |       <a href="../../NATS/JetStream/API/V1/Consumers.html">Consumers</a>
176 |       
177 |     </li>
178 |   
179 |   <li class="parent " data-id="nats/NATS/JetStream/API/V1/ErrorResponse" data-name="nats::jetstream::api::v1::errorresponse">
180 |       <a href="../../NATS/JetStream/API/V1/ErrorResponse.html">ErrorResponse</a>
181 |       
182 |         <ul>
183 |   
184 |   <li class=" " data-id="nats/NATS/JetStream/API/V1/ErrorResponse/Error" data-name="nats::jetstream::api::v1::errorresponse::error">
185 |       <a href="../../NATS/JetStream/API/V1/ErrorResponse/Error.html">Error</a>
186 |       
187 |     </li>
188 |   
189 | </ul>
190 | 
191 |       
192 |     </li>
193 |   
194 |   <li class=" " data-id="nats/NATS/JetStream/API/V1/ExternalStream" data-name="nats::jetstream::api::v1::externalstream">
195 |       <a href="../../NATS/JetStream/API/V1/ExternalStream.html">ExternalStream</a>
196 |       
197 |     </li>
198 |   
199 |   <li class=" " data-id="nats/NATS/JetStream/API/V1/NanosecondsConverter" data-name="nats::jetstream::api::v1::nanosecondsconverter">
200 |       <a href="../../NATS/JetStream/API/V1/NanosecondsConverter.html">NanosecondsConverter</a>
201 |       
202 |     </li>
203 |   
204 |   <li class=" " data-id="nats/NATS/JetStream/API/V1/PeerInfo" data-name="nats::jetstream::api::v1::peerinfo">
205 |       <a href="../../NATS/JetStream/API/V1/PeerInfo.html">PeerInfo</a>
206 |       
207 |     </li>
208 |   
209 |   <li class=" " data-id="nats/NATS/JetStream/API/V1/PubAck" data-name="nats::jetstream::api::v1::puback">
210 |       <a href="../../NATS/JetStream/API/V1/PubAck.html">PubAck</a>
211 |       
212 |     </li>
213 |   
214 |   <li class=" " data-id="nats/NATS/JetStream/API/V1/Stream" data-name="nats::jetstream::api::v1::stream">
215 |       <a href="../../NATS/JetStream/API/V1/Stream.html">Stream</a>
216 |       
217 |     </li>
218 |   
219 |   <li class="parent " data-id="nats/NATS/JetStream/API/V1/StreamConfig" data-name="nats::jetstream::api::v1::streamconfig">
220 |       <a href="../../NATS/JetStream/API/V1/StreamConfig.html">StreamConfig</a>
221 |       
222 |         <ul>
223 |   
224 |   <li class=" " data-id="nats/NATS/JetStream/API/V1/StreamConfig/DiscardPolicy" data-name="nats::jetstream::api::v1::streamconfig::discardpolicy">
225 |       <a href="../../NATS/JetStream/API/V1/StreamConfig/DiscardPolicy.html">DiscardPolicy</a>
226 |       
227 |     </li>
228 |   
229 |   <li class=" " data-id="nats/NATS/JetStream/API/V1/StreamConfig/Placement" data-name="nats::jetstream::api::v1::streamconfig::placement">
230 |       <a href="../../NATS/JetStream/API/V1/StreamConfig/Placement.html">Placement</a>
231 |       
232 |     </li>
233 |   
234 |   <li class=" " data-id="nats/NATS/JetStream/API/V1/StreamConfig/Republish" data-name="nats::jetstream::api::v1::streamconfig::republish">
235 |       <a href="../../NATS/JetStream/API/V1/StreamConfig/Republish.html">Republish</a>
236 |       
237 |     </li>
238 |   
239 |   <li class=" " data-id="nats/NATS/JetStream/API/V1/StreamConfig/RetentionPolicy" data-name="nats::jetstream::api::v1::streamconfig::retentionpolicy">
240 |       <a href="../../NATS/JetStream/API/V1/StreamConfig/RetentionPolicy.html">RetentionPolicy</a>
241 |       
242 |     </li>
243 |   
244 |   <li class=" " data-id="nats/NATS/JetStream/API/V1/StreamConfig/Storage" data-name="nats::jetstream::api::v1::streamconfig::storage">
245 |       <a href="../../NATS/JetStream/API/V1/StreamConfig/Storage.html">Storage</a>
246 |       
247 |     </li>
248 |   
249 | </ul>
250 | 
251 |       
252 |     </li>
253 |   
254 |   <li class="parent " data-id="nats/NATS/JetStream/API/V1/StreamGetMsgResponse" data-name="nats::jetstream::api::v1::streamgetmsgresponse">
255 |       <a href="../../NATS/JetStream/API/V1/StreamGetMsgResponse.html">StreamGetMsgResponse</a>
256 |       
257 |         <ul>
258 |   
259 |   <li class="parent " data-id="nats/NATS/JetStream/API/V1/StreamGetMsgResponse/Message" data-name="nats::jetstream::api::v1::streamgetmsgresponse::message">
260 |       <a href="../../NATS/JetStream/API/V1/StreamGetMsgResponse/Message.html">Message</a>
261 |       
262 |         <ul>
263 |   
264 |   <li class=" " data-id="nats/NATS/JetStream/API/V1/StreamGetMsgResponse/Message/Base64Data" data-name="nats::jetstream::api::v1::streamgetmsgresponse::message::base64data">
265 |       <a href="../../NATS/JetStream/API/V1/StreamGetMsgResponse/Message/Base64Data.html">Base64Data</a>
266 |       
267 |     </li>
268 |   
269 |   <li class=" " data-id="nats/NATS/JetStream/API/V1/StreamGetMsgResponse/Message/HeadersConverter" data-name="nats::jetstream::api::v1::streamgetmsgresponse::message::headersconverter">
270 |       <a href="../../NATS/JetStream/API/V1/StreamGetMsgResponse/Message/HeadersConverter.html">HeadersConverter</a>
271 |       
272 |     </li>
273 |   
274 | </ul>
275 | 
276 |       
277 |     </li>
278 |   
279 | </ul>
280 | 
281 |       
282 |     </li>
283 |   
284 |   <li class=" " data-id="nats/NATS/JetStream/API/V1/StreamListResponse" data-name="nats::jetstream::api::v1::streamlistresponse">
285 |       <a href="../../NATS/JetStream/API/V1/StreamListResponse.html">StreamListResponse</a>
286 |       
287 |     </li>
288 |   
289 |   <li class="parent " data-id="nats/NATS/JetStream/API/V1/Streams" data-name="nats::jetstream::api::v1::streams">
290 |       <a href="../../NATS/JetStream/API/V1/Streams.html">Streams</a>
291 |       
292 |         <ul>
293 |   
294 |   <li class=" " data-id="nats/NATS/JetStream/API/V1/Streams/PurgeStreamResponse" data-name="nats::jetstream::api::v1::streams::purgestreamresponse">
295 |       <a href="../../NATS/JetStream/API/V1/Streams/PurgeStreamResponse.html">PurgeStreamResponse</a>
296 |       
297 |     </li>
298 |   
299 | </ul>
300 | 
301 |       
302 |     </li>
303 |   
304 |   <li class=" " data-id="nats/NATS/JetStream/API/V1/StreamSource" data-name="nats::jetstream::api::v1::streamsource">
305 |       <a href="../../NATS/JetStream/API/V1/StreamSource.html">StreamSource</a>
306 |       
307 |     </li>
308 |   
309 |   <li class=" " data-id="nats/NATS/JetStream/API/V1/StreamSourceInfo" data-name="nats::jetstream::api::v1::streamsourceinfo">
310 |       <a href="../../NATS/JetStream/API/V1/StreamSourceInfo.html">StreamSourceInfo</a>
311 |       
312 |     </li>
313 |   
314 |   <li class=" " data-id="nats/NATS/JetStream/API/V1/StreamState" data-name="nats::jetstream::api::v1::streamstate">
315 |       <a href="../../NATS/JetStream/API/V1/StreamState.html">StreamState</a>
316 |       
317 |     </li>
318 |   
319 | </ul>
320 | 
321 |       
322 |     </li>
323 |   
324 | </ul>
325 | 
326 |       
327 |     </li>
328 |   
329 |   <li class="parent " data-id="nats/NATS/JetStream/Client" data-name="nats::jetstream::client">
330 |       <a href="../../NATS/JetStream/Client.html">Client</a>
331 |       
332 |         <ul>
333 |   
334 |   <li class=" " data-id="nats/NATS/JetStream/Client/NAKBackoff" data-name="nats::jetstream::client::nakbackoff">
335 |       <a href="../../NATS/JetStream/Client/NAKBackoff.html">NAKBackoff</a>
336 |       
337 |     </li>
338 |   
339 | </ul>
340 | 
341 |       
342 |     </li>
343 |   
344 |   <li class=" " data-id="nats/NATS/JetStream/Consumers" data-name="nats::jetstream::consumers">
345 |       <a href="../../NATS/JetStream/Consumers.html">Consumers</a>
346 |       
347 |     </li>
348 |   
349 |   <li class=" " data-id="nats/NATS/JetStream/Error" data-name="nats::jetstream::error">
350 |       <a href="../../NATS/JetStream/Error.html">Error</a>
351 |       
352 |     </li>
353 |   
354 |   <li class=" " data-id="nats/NATS/JetStream/Errors" data-name="nats::jetstream::errors">
355 |       <a href="../../NATS/JetStream/Errors.html">Errors</a>
356 |       
357 |     </li>
358 |   
359 |   <li class=" " data-id="nats/NATS/JetStream/ExternalStream" data-name="nats::jetstream::externalstream">
360 |       <a href="../../NATS/JetStream/ExternalStream.html">ExternalStream</a>
361 |       
362 |     </li>
363 |   
364 |   <li class="parent " data-id="nats/NATS/JetStream/Message" data-name="nats::jetstream::message">
365 |       <a href="../../NATS/JetStream/Message.html">Message</a>
366 |       
367 |         <ul>
368 |   
369 |   <li class=" " data-id="nats/NATS/JetStream/Message/InvalidJetStreamMessage" data-name="nats::jetstream::message::invalidjetstreammessage">
370 |       <a href="../../NATS/JetStream/Message/InvalidJetStreamMessage.html">InvalidJetStreamMessage</a>
371 |       
372 |     </li>
373 |   
374 | </ul>
375 | 
376 |       
377 |     </li>
378 |   
379 |   <li class=" current" data-id="nats/NATS/JetStream/Placement" data-name="nats::jetstream::placement">
380 |       <a href="../../NATS/JetStream/Placement.html">Placement</a>
381 |       
382 |     </li>
383 |   
384 |   <li class=" " data-id="nats/NATS/JetStream/PullSubscription" data-name="nats::jetstream::pullsubscription">
385 |       <a href="../../NATS/JetStream/PullSubscription.html">PullSubscription</a>
386 |       
387 |     </li>
388 |   
389 |   <li class=" " data-id="nats/NATS/JetStream/Streams" data-name="nats::jetstream::streams">
390 |       <a href="../../NATS/JetStream/Streams.html">Streams</a>
391 |       
392 |     </li>
393 |   
394 |   <li class=" " data-id="nats/NATS/JetStream/StreamSource" data-name="nats::jetstream::streamsource">
395 |       <a href="../../NATS/JetStream/StreamSource.html">StreamSource</a>
396 |       
397 |     </li>
398 |   
399 | </ul>
400 | 
401 |       
402 |     </li>
403 |   
404 |   <li class="parent " data-id="nats/NATS/KV" data-name="nats::kv">
405 |       <a href="../../NATS/KV.html">KV</a>
406 |       
407 |         <ul>
408 |   
409 |   <li class="parent " data-id="nats/NATS/KV/Bucket" data-name="nats::kv::bucket">
410 |       <a href="../../NATS/KV/Bucket.html">Bucket</a>
411 |       
412 |         <ul>
413 |   
414 |   <li class=" " data-id="nats/NATS/KV/Bucket/Size" data-name="nats::kv::bucket::size">
415 |       <a href="../../NATS/KV/Bucket/Size.html">Size</a>
416 |       
417 |     </li>
418 |   
419 | </ul>
420 | 
421 |       
422 |     </li>
423 |   
424 |   <li class=" " data-id="nats/NATS/KV/Client" data-name="nats::kv::client">
425 |       <a href="../../NATS/KV/Client.html">Client</a>
426 |       
427 |     </li>
428 |   
429 |   <li class="parent " data-id="nats/NATS/KV/Entry" data-name="nats::kv::entry">
430 |       <a href="../../NATS/KV/Entry.html">Entry</a>
431 |       
432 |         <ul>
433 |   
434 |   <li class=" " data-id="nats/NATS/KV/Entry/Operation" data-name="nats::kv::entry::operation">
435 |       <a href="../../NATS/KV/Entry/Operation.html">Operation</a>
436 |       
437 |     </li>
438 |   
439 | </ul>
440 | 
441 |       
442 |     </li>
443 |   
444 |   <li class=" " data-id="nats/NATS/KV/Error" data-name="nats::kv::error">
445 |       <a href="../../NATS/KV/Error.html">Error</a>
446 |       
447 |     </li>
448 |   
449 |   <li class=" " data-id="nats/NATS/KV/InvalidKeyname" data-name="nats::kv::invalidkeyname">
450 |       <a href="../../NATS/KV/InvalidKeyname.html">InvalidKeyname</a>
451 |       
452 |     </li>
453 |   
454 |   <li class=" " data-id="nats/NATS/KV/KeyEmptyError" data-name="nats::kv::keyemptyerror">
455 |       <a href="../../NATS/KV/KeyEmptyError.html">KeyEmptyError</a>
456 |       
457 |     </li>
458 |   
459 |   <li class=" " data-id="nats/NATS/KV/KeyError" data-name="nats::kv::keyerror">
460 |       <a href="../../NATS/KV/KeyError.html">KeyError</a>
461 |       
462 |     </li>
463 |   
464 |   <li class="parent " data-id="nats/NATS/KV/Watch" data-name="nats::kv::watch">
465 |       <a href="../../NATS/KV/Watch.html">Watch</a>
466 |       
467 |         <ul>
468 |   
469 |   <li class=" " data-id="nats/NATS/KV/Watch/Iterator" data-name="nats::kv::watch::iterator">
470 |       <a href="../../NATS/KV/Watch/Iterator.html">Iterator</a>
471 |       
472 |     </li>
473 |   
474 | </ul>
475 | 
476 |       
477 |     </li>
478 |   
479 | </ul>
480 | 
481 |       
482 |     </li>
483 |   
484 |   <li class="parent " data-id="nats/NATS/Message" data-name="nats::message">
485 |       <a href="../../NATS/Message.html">Message</a>
486 |       
487 |         <ul>
488 |   
489 |   <li class=" " data-id="nats/NATS/Message/Headers" data-name="nats::message::headers">
490 |       <a href="../../NATS/Message/Headers.html">Headers</a>
491 |       
492 |     </li>
493 |   
494 | </ul>
495 | 
496 |       
497 |     </li>
498 |   
499 |   <li class=" " data-id="nats/NATS/NotAReply" data-name="nats::notareply">
500 |       <a href="../../NATS/NotAReply.html">NotAReply</a>
501 |       
502 |     </li>
503 |   
504 |   <li class=" " data-id="nats/NATS/NUID" data-name="nats::nuid">
505 |       <a href="../../NATS/NUID.html">NUID</a>
506 |       
507 |     </li>
508 |   
509 |   <li class="parent " data-id="nats/NATS/Objects" data-name="nats::objects">
510 |       <a href="../../NATS/Objects.html">Objects</a>
511 |       
512 |         <ul>
513 |   
514 |   <li class=" " data-id="nats/NATS/Objects/Bucket" data-name="nats::objects::bucket">
515 |       <a href="../../NATS/Objects/Bucket.html">Bucket</a>
516 |       
517 |     </li>
518 |   
519 |   <li class="parent " data-id="nats/NATS/Objects/Client" data-name="nats::objects::client">
520 |       <a href="../../NATS/Objects/Client.html">Client</a>
521 |       
522 |         <ul>
523 |   
524 |   <li class=" " data-id="nats/NATS/Objects/Client/ObjectInfo" data-name="nats::objects::client::objectinfo">
525 |       <a href="../../NATS/Objects/Client/ObjectInfo.html">ObjectInfo</a>
526 |       
527 |     </li>
528 |   
529 |   <li class=" " data-id="nats/NATS/Objects/Client/Watch" data-name="nats::objects::client::watch">
530 |       <a href="../../NATS/Objects/Client/Watch.html">Watch</a>
531 |       
532 |     </li>
533 |   
534 | </ul>
535 | 
536 |       
537 |     </li>
538 |   
539 |   <li class=" " data-id="nats/NATS/Objects/Error" data-name="nats::objects::error">
540 |       <a href="../../NATS/Objects/Error.html">Error</a>
541 |       
542 |     </li>
543 |   
544 |   <li class=" " data-id="nats/NATS/Objects/KeyError" data-name="nats::objects::keyerror">
545 |       <a href="../../NATS/Objects/KeyError.html">KeyError</a>
546 |       
547 |     </li>
548 |   
549 | </ul>
550 | 
551 |       
552 |     </li>
553 |   
554 |   <li class=" " data-id="nats/NATS/ServerInfo" data-name="nats::serverinfo">
555 |       <a href="../../NATS/ServerInfo.html">ServerInfo</a>
556 |       
557 |     </li>
558 |   
559 |   <li class=" " data-id="nats/NATS/ServerNotRespondingToPings" data-name="nats::servernotrespondingtopings">
560 |       <a href="../../NATS/ServerNotRespondingToPings.html">ServerNotRespondingToPings</a>
561 |       
562 |     </li>
563 |   
564 |   <li class="parent " data-id="nats/NATS/Subscription" data-name="nats::subscription">
565 |       <a href="../../NATS/Subscription.html">Subscription</a>
566 |       
567 |         <ul>
568 |   
569 |   <li class=" " data-id="nats/NATS/Subscription/MessageChannel" data-name="nats::subscription::messagechannel">
570 |       <a href="../../NATS/Subscription/MessageChannel.html">MessageChannel</a>
571 |       
572 |     </li>
573 |   
574 | </ul>
575 | 
576 |       
577 |     </li>
578 |   
579 |   <li class=" " data-id="nats/NATS/UnknownCommand" data-name="nats::unknowncommand">
580 |       <a href="../../NATS/UnknownCommand.html">UnknownCommand</a>
581 |       
582 |     </li>
583 |   
584 | </ul>
585 | 
586 |       
587 |     </li>
588 |   
589 | </ul>
590 | 
591 |   </div>
592 | </div>
593 | 
594 | 
595 | <div class="main-content">
596 | <h1 class="type-name">
597 | 
598 |   <span class="kind">alias</span> NATS::JetStream::Placement
599 | 
600 | </h1>
601 | 
602 | 
603 | 
604 | 
605 | 
606 | 
607 | 
608 |   <h2>
609 |     <a id="alias-definition" class="anchor" href="#alias-definition">
610 |   <svg class="octicon-link" aria-hidden="true">
611 |     <use href="#octicon-link"/>
612 |   </svg>
613 | </a>
614 |     Alias Definition
615 |   </h2>
616 |   <code><a href="../../NATS/JetStream/API/V1/StreamConfig/Placement.html">NATS::JetStream::API::V1::StreamConfig::Placement</a></code>
617 | 
618 | 
619 | 
620 | 
621 | 
622 | 
623 | 
624 | 
625 | 
626 | 
627 | 
628 | 
629 |   <h2>
630 |     <a id="defined-in" class="anchor" href="#defined-in">
631 |   <svg class="octicon-link" aria-hidden="true">
632 |     <use href="#octicon-link"/>
633 |   </svg>
634 | </a>
635 |     Defined in:
636 |   </h2>
637 |   
638 |     
639 |       <a href="https://github.com/jgaskins/nats/blob/v1.2.3/src/jetstream.cr#L401" target="_blank">
640 |         jetstream.cr
641 |       </a>
642 |     
643 |     <br/>
644 |   
645 | 
646 | 
647 | 
648 | 
649 | 
650 | 
651 | 
652 | 
653 | 
654 | 
655 | 
656 | 
657 | 
658 | <div class="methods-inherited">
659 |   
660 | </div>
661 | 
662 | 
663 | 
664 | 
665 | 
666 | 
667 | 
668 | 
669 | 
670 | </div>
671 | 
672 | </body>
673 | </html>
674 | 


--------------------------------------------------------------------------------