Implement class join codes back-end (#789)

This PR implements the back-end for class join codes — students join a
class by entering an 8-character code in the format `CDDD-CDDD`
(consonant + three digits, twice, separated by a hyphen).

## Core Logic

The core logic for this work lives in `JoinController#create`, which
determines what response the front-end gets based on the user who is
trying to join. This method returns a `show.json.builder` with values
that allow the front-end to determine what to show the user, or where to
redirect them to based on their status. The status value is computed in
`action_status`.

Another feature of `JoinController#show` is that it may be called by
unauthenticated users, so that we can destructure the join code into a
school and class in order to show the user a school and class name
before they're redirected to log in.

There are modifications to `School` to allow that model to carry a join
code and regenerate it. Conceptually, a join code is a globally unique
code that represents both a class code and a school code.

The other component of interest is the `JoinCodeGenerator` which
produces the codes in the first place.

## Changes
- Add `join_code` column with a unique index to `school_classes`, plus a
backfill migration for existing classes.
- Add `JoinCodeGenerator` with `.generate` and `.normalize`
(canonicalises user input to the hyphenated form for DB lookup).
- Auto-assign join codes on `SchoolClass` create/import with a
uniqueness retry, plus a `regenerate_join_code!` helper.
- Add `GET /api/join/:join_code` returning the prospective user's
status. The full set of statuses is:
  - `unauthenticated` — no current user
  - `joinable` — the user can be enrolled as a student
- `joinable_as_teacher` — the user already has a teacher role for this
school and will be added to the class as a teacher
- `owner` — the user owns this school; treated as already a member for
redirect purposes
  - `already_member` — the user is already a member of this class
  - `wrong_school` — the user has a role in a different school
- `domain_mismatch` — the user's email domain is not registered for this
school
  - `not_a_student` — the user has a non-student role elsewhere
- Add `POST /api/join/:join_code` to enrol the current user as a student
(or teacher, if `joinable_as_teacher`) of the school and class.
- Add `POST /api/schools/:school_id/classes/:id/regenerate_join_code`
(nested under the existing `school_classes` resource).
- Expose `join_code` on the school class JSON
- Add `School#valid_email?` (built on #787's domain validation) for the
`domain_mismatch` check.
- Add `School#auto_join_enabled?` to allow the front end to prompt users
correctly about the requirements for auto-join.
- Update CanCan abilities so school owners and class teachers can
`regenerate_join_code`.
- Add specs covering the model, generator, controllers, and abilities.

---------

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Author: fspeirs

app/controllers/api/join_controller.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Api
+  class JoinController < ApiController
+    before_action :authorize_user, only: :create
+    before_action :find_school_and_class
+
+    def show
+      @status = show_status
+      render :show, formats: [:json], status: :ok
+    end
+
+    def create
+      case action_status
+      when :wrong_school, :domain_mismatch, :not_a_student
+        render json: { error: action_status.to_s }, status: :forbidden
+      when :already_member, :owner
+        render json: { redirect_url: class_redirect_path }, status: :ok
+      when :joinable_as_teacher
+        add_user_to_class_as_teacher
+        render json: { redirect_url: class_redirect_path }, status: :ok
+      when :joinable
+        add_student_to_school_and_class
+        render json: { redirect_url: class_redirect_path }, status: :ok
+      else
+        raise "Unexpected join action_status: #{action_status.inspect}"
+      end
+    end
+
+    private
+
+    def find_school_and_class
+      @school_class = SchoolClass.find_by!(join_code: JoinCodeGenerator.normalize(params[:join_code]))
+      @school = @school_class.school
+    end
+
+    def show_status
+      return :unauthenticated unless current_user
+
+      action_status
+    end
+
+    def action_status
+      @action_status ||= JoinStatusService.new(school: @school, school_class: @school_class, user: current_user).call
+    end
+
+    def class_redirect_path
+      "/school/#{@school.code}/class/#{@school_class.code}"
+    end
+
+    def add_student_to_school_and_class
+      ActiveRecord::Base.transaction do
+        Role.find_or_create_by!(school: @school, user_id: current_user.id, role: :student)
+        ClassStudent.find_or_create_by!(school_class: @school_class, student_id: current_user.id) do |class_student|
+          class_student.student = current_user
+        end
+      end
+    rescue ActiveRecord::RecordNotUnique
+      # Concurrent join request for the same user/class — DB unique index
+      # caught a race we couldn't catch at validation time. Already enrolled.
+    rescue ActiveRecord::RecordInvalid => e
+      raise unless e.record.errors.of_kind?(:student_id, :taken)
+      # Concurrent join request raced the in-memory uniqueness validator. Already enrolled.
+    end
+
+    def add_user_to_class_as_teacher
+      ClassTeacher.find_or_create_by!(school_class: @school_class, teacher_id: current_user.id) do |class_teacher|
+        class_teacher.teacher = current_user
+      end
+    rescue ActiveRecord::RecordNotUnique
+      # Concurrent join request for the same teacher/class — already enrolled.
+    rescue ActiveRecord::RecordInvalid => e
+      raise unless e.record.errors.of_kind?(:teacher_id, :taken)
+      # Concurrent join raced the in-memory uniqueness validator. Already enrolled.
+    end
+  end
+end

app/controllers/api/school_classes_controller.rb

@@ -81,6 +81,14 @@ def destroy
       end
     end
 
+    def regenerate_join_code
+      @school_class.regenerate_join_code!
+      @school_class_with_teachers = @school_class.with_teachers
+      render :show, formats: [:json], status: :ok
+    rescue ActiveRecord::RecordInvalid
+      render json: { error: @school_class.errors.full_messages.to_sentence }, status: :unprocessable_content
+    end
+
     private
 
     def render_student_index(school_classes)

app/models/ability.rb

@@ -62,7 +62,7 @@ def define_authenticated_non_student_abilities(user)
   def define_school_owner_abilities(school:)
     can(%i[read update destroy], School, id: school.id)
     can(%i[read], :school_member)
-    can(%i[read create import update destroy], SchoolClass, school: { id: school.id })
+    can(%i[read create import update destroy regenerate_join_code], SchoolClass, school: { id: school.id })
     can(%i[read show_context], Project, school_id: school.id, lesson: { visibility: %w[teachers students] })
     can(%i[read create create_batch destroy], ClassStudent, school_class: { school: { id: school.id } })
     can(%i[read create destroy], :school_owner)
@@ -78,7 +78,7 @@ def define_school_teacher_abilities(user:, school:)
     can(%i[read], School, id: school.id)
     can(%i[read], :school_member)
     can(%i[create import], SchoolClass, school: { id: school.id })
-    can(%i[read update destroy], SchoolClass, school: { id: school.id }, teachers: { teacher_id: user.id })
+    can(%i[read update destroy regenerate_join_code], SchoolClass, school: { id: school.id }, teachers: { teacher_id: user.id })
     can(%i[read create create_batch destroy], ClassStudent, school_class: { school: { id: school.id }, teachers: { teacher_id: user.id } })
     can(%i[read], :school_owner)
     can(%i[read], :school_teacher)

app/models/school.rb

@@ -117,13 +117,26 @@ def import_in_progress?
                         .exists?(description: id)
   end
 
+  def auto_join_enabled?
+    school_email_domains.exists?
+  end
+
   def valid_domain?(candidate_domain)
     validated_domain = SchoolEmailDomainValidator.call(candidate_domain)
     school_email_domains.exists?(domain: validated_domain)
   rescue ::SchoolEmailDomainValidator::Error
     false
   end
 
+  def email_domain_in_school_domains?(email)
+    return false if email.blank?
+
+    local, separator, domain = email.to_s.rpartition('@')
+    return false if separator.empty? || local.blank? || domain.blank?
+
+    valid_domain?(domain.strip.downcase)
+  end
+
   private
 
   # Ensure the reference is nil, not an empty string

app/models/school_class.rb

@@ -10,9 +10,11 @@ class SchoolClass < ApplicationRecord
   scope :with_teachers, ->(user_id) { joins(:teachers).where(teachers: { id: user_id }) }
 
   before_validation :assign_class_code, on: %i[create import]
+  before_validation :assign_join_code, on: %i[create import]
 
   validates :name, presence: true
   validates :code, uniqueness: { scope: :school_id }, presence: true, format: { with: /\d\d-\d\d-\d\d/, allow_nil: false }
+  validates :join_code, uniqueness: true, presence: true, format: { with: JoinCodeGenerator::FORMAT_REGEX, allow_nil: false }
   validate :code_cannot_be_changed
   validate :school_class_has_at_least_one_teacher
 
@@ -58,6 +60,27 @@ def assign_class_code
     errors.add(:code, 'could not be generated')
   end
 
+  def assign_join_code
+    return if join_code.present?
+
+    5.times do
+      self.join_code = JoinCodeGenerator.generate
+      return if join_code_is_unique?
+    end
+
+    errors.add(:join_code, 'could not be generated')
+  end
+
+  def regenerate_join_code!
+    self.join_code = nil
+    assign_join_code
+    save!
+  rescue ActiveRecord::RecordNotUnique
+    self.join_code = nil
+    assign_join_code
+    save!
+  end
+
   def submitted_projects_count
     lessons.to_a.sum(&:submitted_projects_count)
   end
@@ -77,4 +100,8 @@ def code_cannot_be_changed
   def code_is_unique_within_school?
     code.present? && SchoolClass.where(code:, school:).none?
   end
+
+  def join_code_is_unique?
+    join_code.present? && SchoolClass.where(join_code:).where.not(id:).none?
+  end
 end

app/services/join_status_service.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+# Computes the join "status" symbol that describes the relationship between
+# `user` and `school_class` — the controller uses it to decide what HTTP
+# response to return and whether to enrol the user.
+#
+# Possible return values:
+#   :already_member       — user is already in this class
+#   :owner                — user owns this school (redirect, no enrolment)
+#   :joinable_as_teacher  — user teaches this school but isn't in the class
+#   :joinable             — user can be enrolled as a student of this class
+#   :not_a_student        — user has a non-student role in some other school
+#   :wrong_school         — user is a student of a different school
+#   :domain_mismatch      — user's email domain isn't registered for the school
+class JoinStatusService
+  def initialize(school:, school_class:, user:)
+    @school = school
+    @school_class = school_class
+    @user = user
+  end
+
+  def call
+    return :already_member if user_is_member_of_class?
+    return existing_user_join_status if user_has_role_in_school?
+
+    new_user_join_status
+  end
+
+  private
+
+  # The user already has a role in this school: which one decides the status.
+  def existing_user_join_status
+    return :owner if user_is_owner_of_school?
+    return :joinable_as_teacher if user_is_teacher_of_school?
+
+    :joinable # student is the only remaining role for this school
+  end
+
+  # The user has no role in this school yet: may they join as a new student?
+  def new_user_join_status
+    return :not_a_student if user_has_non_student_role?
+    return :wrong_school if user_in_different_school?
+    return :domain_mismatch unless @school.email_domain_in_school_domains?(@user.email)
+
+    :joinable
+  end
+
+  def user_is_member_of_class?
+    ClassStudent.exists?(school_class: @school_class, student_id: @user.id) ||
+      ClassTeacher.exists?(school_class: @school_class, teacher_id: @user.id)
+  end
+
+  def user_is_owner_of_school?
+    Role.exists?(school: @school, user_id: @user.id, role: Role.roles[:owner])
+  end
+
+  def user_is_teacher_of_school?
+    Role.exists?(school: @school, user_id: @user.id, role: Role.roles[:teacher])
+  end
+
+  def user_has_role_in_school?
+    Role.exists?(school: @school, user_id: @user.id)
+  end
+
+  def user_has_non_student_role?
+    Role.where(user_id: @user.id).where.not(role: Role.roles[:student]).exists?
+  end
+
+  def user_in_different_school?
+    Role.where(user_id: @user.id).where.not(school_id: @school.id).exists?
+  end
+end

app/views/api/join/show.json.jbuilder

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+json.status @status.to_s
+json.school do
+  json.code @school.code
+  json.name @school.name
+end
+json.school_class do
+  json.code @school_class.code
+  json.name @school_class.name
+end

app/views/api/school_classes/_school_class.json.jbuilder

@@ -9,7 +9,8 @@ json.call(
   :created_at,
   :updated_at,
   :import_origin,
-  :import_id
+  :import_id,
+  :join_code
 )
 
 json.teachers(teachers) do |teacher|

app/views/api/schools/_school.json.jbuilder

@@ -30,3 +30,4 @@ include_user_origin = local_assigns.fetch(:user_origin, false)
 json.user_origin(school.user_origin) if include_user_origin
 
 json.import_in_progress school.import_in_progress?
+json.auto_join_enabled school.auto_join_enabled?

config/routes.rb

@@ -70,6 +70,7 @@
       resources :members, only: %i[index], controller: 'school_members'
       resources :classes, only: %i[index show create update destroy], controller: 'school_classes' do
         post :import, on: :collection
+        post :regenerate_join_code, on: :member
         resources :members, only: %i[index create destroy], controller: 'class_members' do
           post :batch, on: :collection, to: 'class_members#create_batch'
         end
@@ -100,6 +101,9 @@
 
     resources :profile_auth_check, only: %i[index]
     resources :subscriptions, only: %i[create]
+
+    get  '/join/:join_code', to: 'join#show'
+    post '/join/:join_code', to: 'join#create'
   end
 
   resource :github_webhooks, only: :create, defaults: { formats: :json }