Class: SparkConnect::ChannelBuilder

Inherits:
Object
  • Object
show all
Defined in:
lib/spark_connect/channel_builder.rb

Overview

Parses a Spark Connect connection string (sc://...) and builds the gRPC stub, credentials, and per-request metadata.

The connection string grammar mirrors the official Spark Connect clients:

sc://host[:port][/;param=value;param=value...]

Recognised parameters:

  • token - bearer token; implies TLS and adds an authorization header
  • user_id - the Spark user id
  • user_agent - client user agent (default spark-connect-ruby/<version>)
  • use_ssl - true/false; force TLS on or off
  • session_id - reuse a specific server-side session id (UUID)

Any parameter whose name begins with x- is forwarded verbatim as gRPC request metadata.

Examples:

cb = SparkConnect::ChannelBuilder.new("sc://localhost:15002")
cb.host       #=> "localhost"
cb.port       #=> 15002

Constant Summary collapse

DEFAULT_PORT = 
15_002
PARAM_PREFIX = 
"x-"

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(url) ⇒ ChannelBuilder

Returns a new instance of ChannelBuilder.

Parameters:

  • url (String) —

    an sc:// connection string.

Raises:



46
47
48
49
50
51
52
53
54
55
56
57
58
59
 
# File 'lib/spark_connect/channel_builder.rb', line 46

def initialize(url)
  raise ConnectionError, "Connection string must not be nil" if url.nil?
  raise ConnectionError, "Connection string must start with 'sc://', got: #{url.inspect}" unless url.start_with?("sc://")

  body = url.delete_prefix("sc://")
  endpoint, _, param_str = body.partition("/")
  @params = parse_params(param_str)
  parse_endpoint(endpoint)

  @token = @params["token"]
  @user_id = @params["user_id"]
  @session_id = @params["session_id"]
  @use_ssl = parse_bool(@params["use_ssl"]) || !@token.nil?
end

Instance Attribute Details

#host ⇒ String (readonly)

Returns:

  • (String) 


33
34
35
 
# File 'lib/spark_connect/channel_builder.rb', line 33

def host
  @host
end

#params ⇒ Hash{String=>String} (readonly)

Returns raw connection parameters.

Returns:

  • (Hash{String=>String}) —

    raw connection parameters.



37
38
39
 
# File 'lib/spark_connect/channel_builder.rb', line 37

def params
  @params
end

#port ⇒ Integer (readonly)

Returns:

  • (Integer) 


35
36
37
 
# File 'lib/spark_connect/channel_builder.rb', line 35

def port
  @port
end

#session_id ⇒ String? (readonly)

Returns:

  • (String, nil) 


43
44
45
 
# File 'lib/spark_connect/channel_builder.rb', line 43

def session_id
  @session_id
end

#token ⇒ String? (readonly)

Returns:

  • (String, nil) 


39
40
41
 
# File 'lib/spark_connect/channel_builder.rb', line 39

def token
  @token
end

#user_id ⇒ String? (readonly)

Returns:

  • (String, nil) 


41
42
43
 
# File 'lib/spark_connect/channel_builder.rb', line 41

def user_id
  @user_id
end

Instance Method Details

#build_stub(channel_args: {}) ⇒ Spark::Connect::SparkConnectService::Stub

Build the gRPC stub for the Spark::Connect::SparkConnectService.

Parameters:

  • channel_args (Hash) (defaults to: {}) —

    extra gRPC channel arguments.

Returns:

  • (Spark::Connect::SparkConnectService::Stub) 


91
92
93
94
95
 
# File 'lib/spark_connect/channel_builder.rb', line 91

def build_stub(channel_args: {})
  creds = @use_ssl ? GRPC::Core::ChannelCredentials.new : :this_channel_is_insecure
  args = { "grpc.primary_user_agent" => user_agent }.merge(channel_args)
  Proto::SparkConnectService::Stub.new(target, creds, channel_args: args)
end

#metadata ⇒ Hash{String=>String}

Per-request gRPC metadata derived from the connection string (bearer token plus any x-* parameters).

Returns:

  • (Hash{String=>String}) 


80
81
82
83
84
85
 
# File 'lib/spark_connect/channel_builder.rb', line 80

def metadata
  md = {}
  md["authorization"] = "Bearer #{@token}" if @token
  @params.each { |k, v| md[k] = v if k.start_with?(PARAM_PREFIX) }
  md
end

#ssl? ⇒ Boolean

Returns whether the channel uses TLS.

Returns:

  • (Boolean) —

    whether the channel uses TLS.



62
63
64
 
# File 'lib/spark_connect/channel_builder.rb', line 62

def ssl?
  @use_ssl
end

#target ⇒ String

Returns the gRPC target, e.g. "localhost:15002".

Returns:

  • (String) —

    the gRPC target, e.g. "localhost:15002".



67
68
69
 
# File 'lib/spark_connect/channel_builder.rb', line 67

def target
  "#{host}:#{port}"
end

#user_agent ⇒ String

Returns the effective user agent.

Returns:

  • (String) —

    the effective user agent.



72
73
74
 
# File 'lib/spark_connect/channel_builder.rb', line 72

def user_agent
  @params["user_agent"] || "spark-connect-ruby/#{SparkConnect::VERSION}"
end