Making the api client generic in decidim-module-liquidvoting

[davefrey]

The api client (whether the ruby-client, or the client.rb in decidim-module-liquidvoting), is primarily:

create_vote(proposal_url:, participant_email:, yes:)
delete_vote(proposal_url:, participant_email:)

create_delegation(proposal_url:, delegator_email:, delegate_email:)
delete_delegation(proposal_url:, delegator_email:, delegate_email:)

Clients also have a need to know the current voting/delegation state for a user and proposal. Today in our module, we address that by adding the following to the client.rb file:

current_proposal_state(participant_email, proposal_url)
  returns ProposalState = Struct.new(:user_has_voted, :delegate_email)

Since that is kind of Decidim-specific, and we want that client.rb file to be replaceable with the (general) ruby-client gem, we need another solution.

A couple of solutions are to have clients write graphql queries for their needs, and either add a generic method for passing the query, or expose the CLIENT object for the same reason.

Maybe a better way is to stay with a specific, closed method to return the state information, but to make it generic enough to hopefully meet future needs.

So here's an extended, renamed version of our current_proposal_state method that meets the needs I can think of right now:

UserProposalState = Struct.new(
  user_has_voted,     # (exists today) boolean
  user_weight,        # integer count of all direct and indirect delegations to user_email
  user_direct_delegations, # integer count of only the direct delegations to user_email 

  delegate_email,     # (exists today) present when user delegated
  delegate_weight,    # integer count of all direct and indirect delegations to delegate_email
  delegate_status,    # the delegate has [:voted, :delegated, :no_action_yet]

  vote_status,        # voting overall is [:open, :closed, :unknown]; tells if info above is frozen
)
user_proposal_state(user_email, proposal_url)
  returns UserProposalState info

An important attribute for the client is:

  vote_visibility,    # voting is [:private, :public]

but LV doesn't support closing elections yet, this must be a client-determined thing.

So, reactions to this proposed generic api interface?

create_vote(proposal_url:, participant_email:, yes:)
delete_vote(proposal_url:, participant_email:)

create_delegation(proposal_url:, delegator_email:, delegate_email:)
delete_delegation(proposal_url:, delegator_email:, delegate_email:)

user_proposal_state(user_email:, proposal_url:)

[oliverbarnes]

If user_proposal_state is generic enough that other platforms would use, I'd go for it. If we then integrate with, say, Consul, and we then have to jump hoops to keep it generic, then probably this shouldn't be in the client. My feeling at this point is that only the CRUD methods are safely generic enough.

Going over the boundaries:

• I see the client.rb / ruby-client as solely the generic API client
• decidim-module-liquidvoting as the "decidim-lv-client"
• Decidim itself

Besides solving the api client's scope so it can be gemified, there's the issue of distinguishing what is LV specific stuff within the module. Some stuff is clear, like the client calls to create votes.

Then there's the Proposal#update_with_lv_vote_count discussed on #62 (comment). This new naming makes it clear it's LV, at least.

But I'm wondering whether an intermediate object that encapsulated all LV-specific state, both in-memory and interfacing with the db, would make it easy find LV-specific stuff in a single scope. So that we'd have

module LV
  def user_proposal_state(user_email, proposal_url)
    # Talks to the api through the client module
  end

  def update_vote_count(proposal)
    # Saves to the db using activerecord's proposal.update_column() 
  end
end

Come to think of it, LV could just map out to the existing Decidim::Liquidvoting namespace, and user_proposal_state could simply be moved up there from the Client. So that

module Decidim
  module Liquidvoting
    def user_proposal_state(user_email, proposal_url)
      # Talks to the api through the client
    end

    def update_vote_count(proposal)
      # Saves to the db using activerecord's update_column() 
    end

    module Client
      # and this would be replaced with an import/include of the client in the gem
    end
  end
end

What do you think?

[davefrey]

See also further implementation details in #48