============================= Funcionalidades de cliente PC ============================= A continuación se detallan comportamientos adicionales a Timer que se relacionan únicamente con el cliente PC. Inicio de sesión maestro ======================== En caso de requerir el desbloqueo manual de una PC por parte de un asistente, es posible ingresar directamente a la PC para terminarla y liberar el equipo del bloqueo de la aplicación. Dicho ingreso es efectuado proporcionando una llave de ingreso maestra a la aplicación y así liberando el uso de la misma. A continuación, se indica el comportamiento seguido para actualizar y hacer uso de la clave de ingreso maestra. Inicialización de clave *********************** El valor de clave maestra es proporcionado durante la inicialización del servidor Onsite, mismo que debe ser cifrado para su almacenamiento con el algoritmo AES-256, siendo la llave el ``secret`` del Access Key del usuario. El arranque inicial del servidor debe abortarse si se presenta alguno de los siguientes casos al validar la clave maestra: - Si la longitud de la cadena está fuera del rango `[6, 10]`. - Si la cadena contiene algún carácter no alfanumérico. - Si no cuenta con al menos una cadena y al menos un número. Actualización de clave ********************** Flujo ----- Onsite: ``PUT /master_key`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^ **Autorización:** User (*super*, *onsite*) Actualiza el valor de la clave maestra en el sistema, cifrada con el algoritmo AES-256, y siendo la llave el ``secret`` del Access Key asociado a la sucursal. El cuerpo de la petición es el siguiente: .. code-block:: yaml key: alejandra La ruta responde con el estado ``204 No Content``, indicando así que el cambio de clave fue exitoso. Si se desea modificar la clave dentro del horario operativo de la sucursal, se responde con el estado ``403 Forbidden``. Adicionalmente, se responde con el estado ``400 Bad Request`` si se presenta alguno de los siguientes casos: - Si la longitud de la cadena está fuera del rango `[6, 10]`. - Si la cadena contiene algún carácter no alfanumérico. - Si no cuenta con al menos una cadena y al menos un número. Consulta y uso de clave ************************ Flujo ----- Onsite: ``GET /master_key`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^ **Autorización:** User (*super*, *onsite*) Solicita al servidor Onsite la clave maestra en texto plano. La ruta responde con el estado ``200 OK`` acompañado de la siguiente información: .. code-block:: yaml key: alejandro Onsite: ``GET /master_key/aes`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ **Autorización:** Timer Solicita al servidor Onsite la clave maestra. En consecuencia, Onsite cifra la clave usando el algoritmo AES-256, y siendo la llave el ``secret`` del Access Key asociado al Timer. La ruta responde con el estado ``200 OK`` acompañado de la siguiente información: .. code-block:: yaml hashedKey: JjLLTagic1w236OCia03Mg== El cliente debe ejecutar esta petición al inicio de la operación de la aplicación, y una respuesta exitosa debe ser un prerrequisito para el lanzamiento de ésta. En caso de solicitarse un inicio de sesión maestro en el cliente PC, se sigue uno de los siguientes casos: 1. Si el cliente PC cuenta con comunicación hacia Onsite, se lleva a cabo la petición y el resultado es almacenado localmente. 2. Si no es posible lograr comunicación con Onsite, el cliente PC verifica la contraseña ingresada por el asistente contra aquella almacenada desde el inicio de la aplicación. En cualquier caso, la falta de coincidencia entre la clave almacenada y aquella introducida deniega el ingreso maestro a un cliente PC. Obtención de tweets =================== El cliente PC posee la funcionalidad de mantener al tanto al usuario de los tweets publicados por la cuenta *arenaplace2play*. El proceso que se describe a continuación plantea la manera de obtener los tweets, guardarlos en memoria en el servidor Offsite y, posteriormente, devolverlos al cliente PC que lo solicite. La documentación del API de Twitter puede ser consultada en `Twitter Developer Documentation `_. Twitter provee a los desarrolladores con una consola de pruebas en `API Console `_. Autenticación Offsite - Twitter ******************************* Para el siguiente flujo se requiere que el servidor Offsite cuente con las llaves ``consumer key`` y ``secret``, los cuales son configurados al momento de la instalación y por motivos de seguridad no son incluidos en el presente documento. Una descripción más detallada del flujo se proporciona en `Application-only authentication `_. Descripción general ------------------- .. image:: /images/twitter/offsite_twitter_auth_overview.svg :align: center 1. El servidor Offsite codifica su llave y su secreto en una única en base 64 para posteriormente solicitar al API Twitter un cambio de estas credenciales por un bearer token. 2. El API Twitter responde con un bearer token, mismo que Offsite usará en peticiones subsecuentes al API REST para autenticarse. Flujo ----- .. image:: /images/twitter/offsite_twitter_auth_sequence.svg :align: center Las llaves ``consumer key`` y ``password`` son codificadas para obtener un bearer token de la siguiente manera 1. Codificar las llaves en formato URL. Este paso no es requerido debido al formato actual de las llaves, pero debe ser tomado en cuenta en caso de que Twitter actualice el formato de las mismas. 2. Concatenar el ``consumer key`` codificado, un caracter de *dos puntos* (**:**), y el ``secret`` codificado. 3. Codificar usando base 64 la cadena del paso anterior. Posteriormente, debe invocarse la ruta Twitter API: ``POST /oauth2/token`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Mediante la cual se obtiene un *bearer token* asociado a la pareja (``consumer key``, ``password``). La petición debe llevar como *body* la cadena ``grant_type=client_credentials`` y como encabezados los siguientes valores +------------------------+----------------------------------------------------+ | Encabezado | Valor | +========================+====================================================+ | Authorization | ``Basic `` | +------------------------+----------------------------------------------------+ | Content-Type | ``application/x-www-form-urlencoded;charset=UTF-8``| +------------------------+----------------------------------------------------+ Si la operación fue exitosa, el API responde con el estado ``200 OK`` acompañado del token solicitado en el siguiente formato .. code-block:: javascript { "token_type": "bearer", "access_token": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA/AAAAAAAAAAAAAAAAAAAA=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" } Consulta de tweets desde Offsite ================================ Para el siguiente flujo se requiere que el servidor Offsite cuente con un bearer token como se describe en la sección anterior; esto con el fin de autenticar sus peticiones. Una biblioteca para node.js con funciones de cliente hacie el API de Twitter puede consultarse `aquí `_. Descripción general ******************* .. image:: /images/twitter/offsite_tweet_fetch_overview.svg :align: center 1. El servidor Offsite solicita los *n* últimos tweets generados por la cuenta *arenaplace2play*. 2. El API de Twitter devuelve los tweets solicitados y son almacenados localmente por Offsite. Flujo ***** Se hace uso de la ruta ``https://api.twitter.com/1.1/statuses/user_timeline.json`` para obtener los tweets del usuario que se indique como ``screen_name``. Un ejemplo de la petición haciendo uso de la biblioteca *twitter* de node.js como sigue .. code-block:: javascript var params = {screen_name: 'arenaplace2play'}; client.get('statuses/user_timeline', params, function(error, tweets, response) { if (!error) { console.log(tweets); // Write tweets to file } }); Las peticiones a la ruta ``statuses/user_timeline`` deben efectuarse con los siguientes parámetros =========== =================== ============================= Parámetro Valor Función ----------- ------------------- ----------------------------- screen_name ``arenaplace2play`` El nombre del usuario para el cual devolver resultados trim_user ``true`` Para devolver una versión reducida de datos del usuario count 30 Solicita los 30 últimos tweets since_id Ver nota Para devolver resultados a partir de un índice =========== =================== ============================= .. note:: Con el objetivo de solicitar únicamente los tweets con los que no cuenta el servidor Offsite y no redundar información, se hace uso del campo *since_id*. El valor de dicho campo debe corresponder con el identificador del último tweet con el que se cuente en el sistema. El campo *since_id* es excluyente, esto es, el tweet a partir del cual se solicita nueva información no es incluido en la respuesta. Como excepción, el tweet referenciado en *since_id* es incluido si el número de tweets solicitados en el campo *count* excede el disponible. En caso de tratarse de la primera petición para obtener tweets, el campo *since_id* es omitido. La respuesta de Twitter al solicitar el histórico de tweets sigue el siguiente formato .. code-block:: javascript [{ "created_at": "Mon Jan 23 01:13:25 +0000 2017", "id": 823337809763299300, "id_str": "823337809763299328", "text": "“Does anyone claim to have a particularly fine Jenkins install that I can steal? Something they’re...” https://t.co/9VxglBOJAB", "truncated": false, "entities": { "hashtags": [], "symbols": [], "user_mentions": [], "urls": [{ "url": "https://t.co/9VxglBOJAB", "expanded_url": "https://tmblr.co/ZLYJno2HWjQuu", "display_url": "tmblr.co/ZLYJno2HWjQuu", "indices": [ 103, 126 ] }] }, "source": "Tumblr", "in_reply_to_status_id": null, "in_reply_to_status_id_str": null, "in_reply_to_user_id": null, "in_reply_to_user_id_str": null, "in_reply_to_screen_name": null, "user": { "id": 37792401, "id_str": "37792401" }, "geo": null, "coordinates": null, "place": null, "contributors": null, "is_quote_status": false, "retweet_count": 0, "favorite_count": 0, "favorited": false, "retweeted": false, "possibly_sensitive": false, "lang": "en" }] Los tweets recibidos en el formato anterior deben ser recortados para almacenar únicamente la información requerida por el cliente. Un objeto *tweet* recortado será almacenado en la base de datos tomando en cuenta únicamente los siguientes campos .. code-block:: javascript { "created_at": "Mon Jan 23 01:13:25 +0000 2017", "id": 823337809763299300, "id_str": "823337809763299328", "text": "“Does anyone claim to have a particularly fine Jenkins install that I can steal? Something they’re...” https://t.co/9VxglBOJAB", "truncated": false } El servidor Offsite contará en todo momento con 30 tweets disponibles al cliente PC. Si la cantidad de tweets en el archivo es mayor a 30, se eliminan los tweets más antiguos para mantener el número. El servidor Offsite realizará una consulta al API de Twitter no más de una vez cada 5 minutos. De haber transcurrido menos de 5 minutos de una petición de tweets por parte de un cliente PC, Offsite devolverá el caché sin consultar Twitter. Consulta de tweets desde PC *************************** Un cliente PC solicita periódicamente al servidor Offsite los tweets almacenados en el servidor. A continuación se describe el proceso de consulta de tweets. Descripción general ------------------- .. image:: /images/twitter/pc_tweet_fetch_overview.svg :align: center 1. El cliente de PC realiza una consulta al servidor Offsite para obtener los últimos tweets para mostrar al usuario. 2. Offsite consulta con el API de Twitter si existen nuevos tweets generados por la cuenta predefinida. En caso de ser así, el servidor actualiza su archivo de tweets. 3. Offsite devuelve el caché de tweets al cliente PC. Flujo ----- .. image:: /images/twitter/pc_tweet_fetch_overview.svg :align: center Offsite: ``GET /tweet_timeline`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ **Autorización:** Timer Mediante este ruta, se consultan los 30 últimos tweets generados por la cuenta *arenaplacetoplay*. Esta ruta responde con el estado ``200 OK`` acompañado de los tweets ordenados de manera decreciente por fecha siguiendo el siguiente formato .. code-block:: javascript [{ "id": 8, "createdAt": "Mon Jan 23 01:13:25 +0000 2017", "tid": 823337809763299300, "tidStr": "823337809763299328", "text": "“Does anyone claim to have a particularly fine Jenkins install that I can steal? Something they’re...” https://t.co/9VxglBOJAB", "truncated": false }] De ocurrir un error de comunicación con el servidor de Twitter, la ruta responde con los últimos tweets en la memoria de Offsite. Restricciones sobre la consulta de tweets ***************************************** Twitter impone una restricción de un máximo de 1500 consultas por ventana de tiempo de 15 minutos, por lo que una cantidad de consultas mayor a esta cantidad devolverá un error. Como consecuencia, se devolverá al cliente de PC el contenido del caché de tweets. Los errores sobre operaciones no permitidas son devueltos por Twitter con el estado ``403 Forbidden`` y un objeto de error en el cuerpo como el siguiente .. code-block:: javascript { "errors": [{ "code": 99, "label": "authenticity_token_error", "message": "Unable to verify your credentials" }] }