live 0.2.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f33999c1164c25bd9fccfac8d7be846b6ad536ae04da0302b450662a7db1624f
-  data.tar.gz: 0bbd2f3b7b06819b9ae5cb8b057277a1885fe7d44598238a46d21704eb62173c
+  metadata.gz: e6f7751e42637cac42f2129ab5acbe1ef1c5109a10ef8f1c380b98e2d986829b
+  data.tar.gz: f7686de5fa9fd454568d4ccc5735b9146b70a23643e7611da6a0578d5b1213c9
 SHA512:
-  metadata.gz: a5bcd37c979d0155cd70b822f7959ae7d97661c7652f2e945cc9b9ff6ff4a099600894f8348b0b135abeb90dd1156e724ed2b063b68c2c908c5823240b41af3c
-  data.tar.gz: 68aae390d5d46ca5e81d4f333a40d3db1e9fbf8394d41600576dace4b0a2bd2df5c94ab8795cbdd156bab01e07ecc0b372d84853c5e99c965481b4fb1f9a0ce6
+  metadata.gz: 5dbd73c760708403ad2d16c4343bfc850fd381bb1d37c6d129327015597653227c8b812d6e3eea34b23960cc87d849f9a6cefa97d3154e17c2c6236dbcc7fe33
+  data.tar.gz: 613b770cfeb6c1ef2bfd9b0972186e92361ba4774d3b6786b24bceb698da82ced5b817b5427cff6994a88a692e52b77448d490448761b277f53b7374b86becfe

data/lib/live/element.rb

@@ -23,7 +23,10 @@
 require 'json'
 
 module Live
+	# Represents a single dynamic content area on the page.
 	class Element
+		# @parameter id [String] The unique identifier within the page.
+		# @parameter data [Hash] The data associated with the element, typically stored as `data-` attributes.
 		def initialize(id, **data)
 			@id = id
 			@data = data
@@ -32,8 +35,11 @@ module Live
 			@page = nil
 		end
 		
+		# The unique id within the bound page.
 		attr :id
 		
+		# Generate a JavaScript string which forwards the specified event to the server.
+		# @parameter details [Hash] The details associated with the forwarded event.
 		def forward(details = nil)
 			if details
 				"live.forward(#{JSON.dump(@id)}, event, #{JSON.dump(details)})"
@@ -42,13 +48,24 @@ module Live
 			end
 		end
 		
+		# Bind this tag to a dynamically updating page.
+		# @parameter page [Live::Page]
 		def bind(page)
 			@page = page
 		end
 		
-		def handle(event, details)
+		def close
+			@page = nil
+		end
+		
+		# Handle a client event, typically as triggered by {#forward}.
+		# @parameter event [String] The type of the event.
+		def handle(event)
 		end
 		
+		# Enqueue a remote procedure call to the currently bound page.
+		# @parameter method [Symbol] The name of the remote functio to invoke.
+		# @parameter arguments [Array]
 		def rpc(method, arguments)
 			# This update might not be sent right away. Therefore, mutable arguments may be serialized to JSON at a later time (or never). This could be a race condition:
 			@page.updates.enqueue([method, arguments])

data/lib/live/page.rb

@@ -26,8 +26,12 @@ require_relative 'resolver'
 require 'async'
 require 'async/queue'
 
+require 'protocol/websocket/json_message'
+
 module Live
+	# Represents a connected client page with bound dynamic content areas.
 	class Page
+		# @parameter resolver [Live::Resolver] Used to resolve client-side elements to server-side element instances.
 		def initialize(resolver)
 			@resolver = resolver
 			
@@ -35,21 +39,33 @@ module Live
 			@updates = Async::Queue.new
 		end
 		
+		# The queue of outstanding events to be sent to the client.
 		attr :updates
 		
+		# Bind a client-side element to a server side element.
+		# @parameter element [Live::Element] The element to bind.
 		def bind(element)
 			@elements[element.id] = element
 			
 			element.bind(self)
 		end
 		
+		# Resolve a client-side element to a server side instance.
+		# @parameter id [String] The unique identifier within the page.
+		# @parameter data [Hash] The data associated with the element, typically stored as `data-` attributes.
 		def resolve(id, data)
 			@resolver.call(id, data)
 		end
 		
-		def handle(id, event, details)
+		# Handle an event from the client. If the element could not be found, it is silently ignored.
+		# @parameter id [String] The unique identifier of the element which forwarded the event.
+		# @parameter event [String] The type of the event.
+		# @parameter details [Hash] The associated details if any.
+		# @returns [Object] The result of the element handler, if the element was found.
+		# @returns [Nil] If the element could not be found.
+		def handle(id, event)
 			if element = @elements[id]
-				return element.handle(event, details)
+				return element.handle(event)
 			else
 				Console.logger.warn(self, "Could not handle event:", event, details)
 			end
@@ -57,39 +73,51 @@ module Live
 			return nil
 		end
 		
-		def run(connection)
-			reader_task = start_reader(connection)
-			
-			while update = @updates.dequeue
-				Console.logger.debug(self, "Sending update:", update)
-				
-				connection.write(update)
-				connection.flush if @updates.empty?
+		def close
+			@elements.each do |id, element|
+				element.close
 			end
-		ensure
-			reader_task&.stop
 		end
 		
-		private
+		# Process a single incoming message from the network.
+		def process_message(message)
+			if id = message[:bind] and data = message[:data]
+				if element = self.resolve(id, data)
+					self.bind(element)
+				else
+					Console.logger.warn(self, "Could not resolve element:", message)
+				end
+			elsif id = message[:id]
+				self.handle(id, message[:event])
+			else
+				Console.logger.warn(self, "Unhandled message:", message)
+			end
+		end
 		
-		def start_reader(connection)
-			Async do
-				while message = connection.read
-					Console.logger.debug(self, "Reading message:", message)
+		# Run the event handling loop with the given websocket connection.
+		# @parameter connection [Async::WebSocket::Connection]
+		def run(connection)
+			queue_task = Async do
+				while update = @updates.dequeue
+					Console.logger.debug(self, "Sending update:", update)
 					
-					if id = message[:bind] and data = message[:data]
-						if element = self.resolve(id, data)
-							self.bind(element)
-						else
-							Console.logger.warn(self, "Could not resolve element:", message)
-						end
-					elsif id = message[:id]
-						self.handle(id, message[:event], message[:details])
-					else
-						Console.logger.warn(self, "Unhandled message:", message)
-					end
+					connection.write(::Protocol::WebSocket::JSONMessage.generate(update))
+					connection.flush if @updates.empty?
 				end
 			end
+			
+			while message = connection.read
+				Console.logger.debug(self, "Reading message:", message)
+				
+				if json_message = ::Protocol::WebSocket::JSONMessage.wrap(message)
+					process_message(json_message.parse)
+				else
+					Console.logger.warn(self, "Unhandled message:", message)
+				end
+			end
+		ensure
+			self.close
+			queue_task&.stop
 		end
 	end
 end

data/lib/live/resolver.rb

@@ -34,6 +34,7 @@ module Live
 			@allowed = {}
 		end
 		
+		# @attribute [Hash(String, Class)] A map of allowed class names.
 		attr :allowed
 		
 		def freeze

data/lib/live/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Live
-  VERSION = "0.2.0"
+  VERSION = "0.5.0"
 end

data/lib/live/view.rb

@@ -24,22 +24,31 @@ require_relative 'element'
 require 'trenni/builder'
 
 module Live
+	# Represents a single division of content on the page an provides helpers for rendering the content.
 	class View < Element
+		# Replace the content of the client-side element by rendering this view.
 		def replace!
 			rpc(:replace, [@id, self.to_html])
 		end
 		
-		def append!(node)
-			rpc(:append, [@id, node.to_html])
+		# Append to the content of the client-side element by appending the specified element.
+		# @parameter node [Live::Element] The element to append.
+		def append!(element)
+			rpc(:append, [@id, element.to_html])
 		end
 		
-		def prepend!(node)
-			rpc(:prepend, [@id, node.to_html])
+		# Prepend to the content of the client-side element by appending the specified element.
+		# @parameter node [Live::Element] The element to prepend.
+		def prepend!(element)
+			rpc(:prepend, [@id, element.to_html])
 		end
 		
+		# Render the element.
+		# @parameter builder [Trenni::Builder] The HTML builder.
 		def render(builder)
 		end
 		
+		# @returns [Object] The generated HTML.
 		def to_html
 			Trenni::Builder.fragment do |builder|
 				builder.tag :div, id: @id, class: 'live', data: @data do

metadata

@@ -1,31 +1,60 @@
 --- !ruby/object:Gem::Specification
 name: live
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Samuel Williams
 autorequire:
 bindir: bin
-cert_chain: []
-date: 2021-04-19 00:00:00.000000000 Z
+cert_chain:
+- |
+  -----BEGIN CERTIFICATE-----
+  MIIE2DCCA0CgAwIBAgIBATANBgkqhkiG9w0BAQsFADBhMRgwFgYDVQQDDA9zYW11
+  ZWwud2lsbGlhbXMxHTAbBgoJkiaJk/IsZAEZFg1vcmlvbnRyYW5zZmVyMRIwEAYK
+  CZImiZPyLGQBGRYCY28xEjAQBgoJkiaJk/IsZAEZFgJuejAeFw0yMjA4MDYwNDUz
+  MjRaFw0zMjA4MDMwNDUzMjRaMGExGDAWBgNVBAMMD3NhbXVlbC53aWxsaWFtczEd
+  MBsGCgmSJomT8ixkARkWDW9yaW9udHJhbnNmZXIxEjAQBgoJkiaJk/IsZAEZFgJj
+  bzESMBAGCgmSJomT8ixkARkWAm56MIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIB
+  igKCAYEAomvSopQXQ24+9DBB6I6jxRI2auu3VVb4nOjmmHq7XWM4u3HL+pni63X2
+  9qZdoq9xt7H+RPbwL28LDpDNflYQXoOhoVhQ37Pjn9YDjl8/4/9xa9+NUpl9XDIW
+  sGkaOY0eqsQm1pEWkHJr3zn/fxoKPZPfaJOglovdxf7dgsHz67Xgd/ka+Wo1YqoE
+  e5AUKRwUuvaUaumAKgPH+4E4oiLXI4T1Ff5Q7xxv6yXvHuYtlMHhYfgNn8iiW8WN
+  XibYXPNP7NtieSQqwR/xM6IRSoyXKuS+ZNGDPUUGk8RoiV/xvVN4LrVm9upSc0ss
+  RZ6qwOQmXCo/lLcDUxJAgG95cPw//sI00tZan75VgsGzSWAOdjQpFM0l4dxvKwHn
+  tUeT3ZsAgt0JnGqNm2Bkz81kG4A2hSyFZTFA8vZGhp+hz+8Q573tAR89y9YJBdYM
+  zp0FM4zwMNEUwgfRzv1tEVVUEXmoFCyhzonUUw4nE4CFu/sE3ffhjKcXcY//qiSW
+  xm4erY3XAgMBAAGjgZowgZcwCQYDVR0TBAIwADALBgNVHQ8EBAMCBLAwHQYDVR0O
+  BBYEFO9t7XWuFf2SKLmuijgqR4sGDlRsMC4GA1UdEQQnMCWBI3NhbXVlbC53aWxs
+  aWFtc0BvcmlvbnRyYW5zZmVyLmNvLm56MC4GA1UdEgQnMCWBI3NhbXVlbC53aWxs
+  aWFtc0BvcmlvbnRyYW5zZmVyLmNvLm56MA0GCSqGSIb3DQEBCwUAA4IBgQB5sxkE
+  cBsSYwK6fYpM+hA5B5yZY2+L0Z+27jF1pWGgbhPH8/FjjBLVn+VFok3CDpRqwXCl
+  xCO40JEkKdznNy2avOMra6PFiQyOE74kCtv7P+Fdc+FhgqI5lMon6tt9rNeXmnW/
+  c1NaMRdxy999hmRGzUSFjozcCwxpy/LwabxtdXwXgSay4mQ32EDjqR1TixS1+smp
+  8C/NCWgpIfzpHGJsjvmH2wAfKtTTqB9CVKLCWEnCHyCaRVuKkrKjqhYCdmMBqCws
+  JkxfQWC+jBVeG9ZtPhQgZpfhvh+6hMhraUYRQ6XGyvBqEUe+yo6DKIT3MtGE2+CP
+  eX9i9ZWBydWb8/rvmwmX2kkcBbX0hZS1rcR593hGc61JR6lvkGYQ2MYskBveyaxt
+  Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
+  voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
+  -----END CERTIFICATE-----
+date: 2022-08-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: trenni
+  name: async-websocket
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.22.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.22.0
 - !ruby/object:Gem::Dependency
-  name: async-websocket
+  name: trenni
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -125,7 +154,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.3
+rubygems_version: 3.3.7
 signing_key:
 specification_version: 4
 summary: Live HTML tags updated via a WebSocket.