/*

 *   This program is free software; you can redistribute it and/or modify

 *   it under the terms of the GNU General Public License as published by

 *   the Free Software Foundation; either version 2 of the License, or

 *   (at your option) any later version.

 *

 *   This program is distributed in the hope that it will be useful,

 *   but WITHOUT ANY WARRANTY; without even the implied warranty of

 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

 *   GNU General Public License for more details.

 *

 *   You should have received a copy of the GNU General Public License

 *   along with this program; if not, write to the Free Software

 *   Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA

 */

/**

 * $Id: 47dbf6292397779aaf1d60d67379d095bc5b2eac $

 *

 * @file unlang/child_request.c

 * @brief Common child request management code.

 *

 * @copyright 2021 Arran Cudbard-Bell (a.cudbardb@freeradius.org)

 */

#include <freeradius-devel/server/state.h>

#include <freeradius-devel/unlang/mod_action.h>

#include "unlang_priv.h"

#include "child_request_priv.h"

typedef struct {

  unlang_child_request_t *cr;   //!< A pointer to memory in the parent's frame state

            ///< allocated for this child to write results to.

} unlang_frame_state_child_request_t;

fr_table_num_ordered_t const unlang_child_states_table[] = {

  { L("CANCELLED"),   CHILD_CANCELLED },

  { L("DETACH"),      CHILD_DETACHED  },

  { L("DONE"),      CHILD_DONE  },

  { L("EXITED"),      CHILD_EXITED  },

  { L("INIT"),      CHILD_INIT  },

  { L("RUNNABLE"),    CHILD_RUNNABLE  }

};

size_t unlang_child_states_table_len = NUM_ELEMENTS(unlang_child_states_table);

/** Process a detach signal in the child

 *

 * This processes any detach signals the child receives

 * The child doesn't actually do the detaching

 */

static void unlang_child_request_signal(request_t *request, UNUSED unlang_stack_frame_t *frame, fr_signal_t action)

{

  unlang_frame_state_child_request_t *state;

  unlang_child_request_t *cr;

  /*

   *  We're already detached so we don't

   *  need to notify the parent we're

   *  waking up, and we don't need to detach

   *  again...

   */

  if (request_is_detached(request)) return;

  state = talloc_get_type_abort(frame->state, unlang_frame_state_child_request_t);

  cr = state->cr; /* Can't use talloc_get_type_abort, may be an array element */

  /*

   *  Ignore signals which aren't detached, and

   *  are ignore the signal if we have no parent.

   */

  switch (action) {

  case FR_SIGNAL_DETACH:

    /*

     *  Place child's state back inside the parent

     */

    if (cr->config.session_unique_ptr) fr_state_store_in_parent(request,

                      cr->config.session_unique_ptr,

                      cr->num);

    RDEBUG3("Detached - Removing subrequest from parent, and marking parent as runnable");

    /*

     *  Indicate to the parent there's no longer a child

     */

    cr->state = CHILD_DETACHED;

    /*

     *  Don't run the request-done frame, the request will have been

     *  detached by whatever signalled us, so we can't inform the parent

     *  when we exit.

     */

    repeatable_clear(frame);

    frame->p_result = &frame->scratch_result;

    /*

     *  Tell the parent to resume if all the request's siblings are done

     */

    if (!cr->sibling_count || (--(*cr->sibling_count) == 0)) unlang_interpret_mark_runnable(request->parent);

    break;

  /*

   *  This frame is not cancellable, so FR_SIGNAL_CANCEL

   *  does nothing.  If the child is cancelled in its

   *  entirety, then its stack will unwind up to this point

   *  and unlang_subrequest_child_done will mark the

   *  parent as runnable.  We don't need to do anything here.

   *

   *  We set the state for debugging purposes, and to reduce

   *  the amount of work we do in unlang_subrequest_child_done.

   */

  case FR_SIGNAL_CANCEL:

    cr->state = CHILD_CANCELLED;

    break;

  default:

    return;

  }

}

/** When the child is done, tell the parent that we've exited.

 *

 * This is pushed as a frame at the top of the child's stack, so when

 * the child is done executing, it runs this to inform the parent

 * that its done.

 */

static unlang_action_t unlang_child_request_done(UNUSED unlang_result_t *p_result, request_t *request, unlang_stack_frame_t *frame)

{

  unlang_frame_state_child_request_t *state = talloc_get_type_abort(frame->state, unlang_frame_state_child_request_t);

  unlang_child_request_t *cr = state->cr; /* Can't use talloc_get_type_abort, may be an array element */

  /*

   *  The repeat function for this frame should've

   *  been cleared, so this function should not run

   *  for detached requests.

   */

  fr_assert(!request_is_detached(request));

  switch (cr->state) {

  case CHILD_RUNNABLE:

    /*

     *  Place child state back inside the parent

     */

    if (cr->config.session_unique_ptr) {

      fr_state_store_in_parent(request,

             cr->config.session_unique_ptr,

             cr->num);

    }

    if (cr->p_result) *cr->p_result = cr->result;

    break;

  case CHILD_CANCELLED:

    /*

     *  Child session state is no longer consistent

     *  after cancellation, so discard it.

     */

    if (cr->config.session_unique_ptr) {

      fr_state_discard_child(request->parent, cr->config.session_unique_ptr, cr->num);

    }

    break;

  default:

    fr_assert_msg(0, "child %s resumed top frame with invalid state %s",

            request->name,

            fr_table_str_by_value(unlang_child_states_table, cr->state, "<INVALID>"));

  }

  cr->state = CHILD_EXITED;

  /*

   *  Tell the parent to resume if all the request's siblings are done

   */

  if (!cr->sibling_count || (--(*cr->sibling_count) == 0)) {

    RDEBUG3("All children have exited, marking parent %s as runnable", request->parent->name);

    unlang_interpret_mark_runnable(request->parent);

  } else {

    RDEBUG3("Child %s exited, %u sibling(s) remaining",

      request->name,

      *cr->sibling_count);

  }

  return UNLANG_ACTION_CALCULATE_RESULT;

}

/** Push a resumption frame onto a child's stack

 *

 * Push a frame onto the stack of the child to inform the parent when it's complete.

 * An additional frame is pushed onto the child's stack by the 'run' function which

 * executes in the context of the parent.

 *

 * @param[in] cr  state for this child request.  This is a pointer

 *      to a structure in the parent's frame state.

 * @return

 *  - 0 on success.

 *  - -1 on failure.

 */

static int unlang_child_request_stack_init(unlang_child_request_t *cr)

{

  request_t       *child = cr->request;

  unlang_frame_state_child_request_t  *state;

  unlang_stack_frame_t      *frame;

  static unlang_t inform_parent = {

    .type = UNLANG_TYPE_CHILD_REQUEST,

    .name = "child-request",

    .debug_name = "child-request-resume",

    .actions = DEFAULT_MOD_ACTIONS,

  };

  /* Sets up the frame for us to use immediately */

  if (unlikely(unlang_interpret_push_instruction(&cr->result, child, &inform_parent,

                   FRAME_CONF(RLM_MODULE_NOOP, true)) < 0)) {

    return -1;

  }

  frame = frame_current(child);

  state = frame->state;

  state->cr = cr;

  repeatable_set(frame);  /* Run this on the way back up */

  return 0;

}

/** Initialize a child request

 *

 * This initializes the child request result and configuration structure,

 * and pushes a resumption frame onto the child's stack.

 *

 * @param[in] ctx     Memory to use for any additional memory allocated

 *          to the unlang_child_request_t.

 * @param[out] out      Child request to initialize.

 * @param[in] child     The child request to initialize.

 * @param[in] p_result      Where to write out the rcode from the child.

 * @param[in,out] sibling_count   If non-null the number of siblings.  This is incremented

 *          for each child created.

 * @param[in] unique_session_ptr  Unique session pointer for this child.

 *          If NULL session data won't be stored/restored for the child.

 * @param[in] free_child    Free the child when done?

 * @return

 *  - 0 on success.

 *  - -1 on failure.

 */

int unlang_child_request_init(TALLOC_CTX *ctx, unlang_child_request_t *out, request_t *child,

            unlang_result_t *p_result, unsigned int *sibling_count, void const *unique_session_ptr, bool free_child)

{

  *out = (unlang_child_request_t){

    .name = talloc_bstrdup(ctx, child->name),

    .num = sibling_count ? (*sibling_count)++ : 0,

    .request = child,

    .state = CHILD_INIT,

    .sibling_count = sibling_count,

    .config = {

      .session_unique_ptr = unique_session_ptr,

      .free_child = free_child

    },

    .p_result = p_result

  };

  return unlang_child_request_stack_init(out);

}

int unlang_child_request_op_init(void)

{

  unlang_register(&(unlang_op_t){

      .name = "child-request",

      .type = UNLANG_TYPE_CHILD_REQUEST,

      /*

       *  Frame can't be cancelled, because children need to

       *  write out status to the parent.  If we don't do this,

       *  then all children must be detachable and must detach

       *  so they don't try and write out status to a "done"

       *  parent.

       *

       *  It's easier to allow the child/parent relationship

       *  to end normally so that non-detachable requests are

       *  guaranteed the parent still exists.

       */

      .flag = UNLANG_OP_FLAG_NO_FORCE_UNWIND | UNLANG_OP_FLAG_INTERNAL,

      .interpret = unlang_child_request_done,

      .signal = unlang_child_request_signal,

      .frame_state_size = sizeof(unlang_frame_state_child_request_t),

      .frame_state_type = "unlang_frame_state_child_request_t"

    });

  return 0;

}