feat(auth): API keys

implements:
https://github.com/meilisearch/specifications/blob/develop/text/0085-api-keys.md

- Add tests on API keys management route (meilisearch-http/tests/auth/api_keys.rs)
- Add tests checking authorizations on each meilisearch routes (meilisearch-http/tests/auth/authorization.rs)
- Implement API keys management routes (meilisearch-http/src/routes/api_key.rs)
- Create module to manage API keys and authorizations (meilisearch-auth)
- Reimplement GuardedData to extend authorizations (meilisearch-http/src/extractors/authentication/mod.rs)
- Change X-MEILI-API-KEY by Authorization Bearer (meilisearch-http/src/extractors/authentication/mod.rs)
- Change meilisearch routes to fit to the new authorization feature (meilisearch-http/src/routes/)

- close #1867

meilisearch-auth/src/action.rs

@@ -0,0 +1,104 @@
+use enum_iterator::IntoEnumIterator;
+use serde::{Deserialize, Serialize};
+
+#[derive(IntoEnumIterator, Copy, Clone, Serialize, Deserialize, Debug, Eq, PartialEq)]
+#[repr(u8)]
+pub enum Action {
+    #[serde(rename = "*")]
+    All = 0,
+    #[serde(rename = "search")]
+    Search = actions::SEARCH,
+    #[serde(rename = "documents.add")]
+    DocumentsAdd = actions::DOCUMENTS_ADD,
+    #[serde(rename = "documents.get")]
+    DocumentsGet = actions::DOCUMENTS_GET,
+    #[serde(rename = "documents.delete")]
+    DocumentsDelete = actions::DOCUMENTS_DELETE,
+    #[serde(rename = "indexes.add")]
+    IndexesAdd = actions::INDEXES_ADD,
+    #[serde(rename = "indexes.get")]
+    IndexesGet = actions::INDEXES_GET,
+    #[serde(rename = "indexes.update")]
+    IndexesUpdate = actions::INDEXES_UPDATE,
+    #[serde(rename = "indexes.delete")]
+    IndexesDelete = actions::INDEXES_DELETE,
+    #[serde(rename = "tasks.get")]
+    TasksGet = actions::TASKS_GET,
+    #[serde(rename = "settings.get")]
+    SettingsGet = actions::SETTINGS_GET,
+    #[serde(rename = "settings.update")]
+    SettingsUpdate = actions::SETTINGS_UPDATE,
+    #[serde(rename = "stats.get")]
+    StatsGet = actions::STATS_GET,
+    #[serde(rename = "dumps.create")]
+    DumpsCreate = actions::DUMPS_CREATE,
+    #[serde(rename = "dumps.get")]
+    DumpsGet = actions::DUMPS_GET,
+    #[serde(rename = "version")]
+    Version = actions::VERSION,
+}
+
+impl Action {
+    pub fn from_repr(repr: u8) -> Option<Self> {
+        use actions::*;
+        match repr {
+            0 => Some(Self::All),
+            SEARCH => Some(Self::Search),
+            DOCUMENTS_ADD => Some(Self::DocumentsAdd),
+            DOCUMENTS_GET => Some(Self::DocumentsGet),
+            DOCUMENTS_DELETE => Some(Self::DocumentsDelete),
+            INDEXES_ADD => Some(Self::IndexesAdd),
+            INDEXES_GET => Some(Self::IndexesGet),
+            INDEXES_UPDATE => Some(Self::IndexesUpdate),
+            INDEXES_DELETE => Some(Self::IndexesDelete),
+            TASKS_GET => Some(Self::TasksGet),
+            SETTINGS_GET => Some(Self::SettingsGet),
+            SETTINGS_UPDATE => Some(Self::SettingsUpdate),
+            STATS_GET => Some(Self::StatsGet),
+            DUMPS_CREATE => Some(Self::DumpsCreate),
+            DUMPS_GET => Some(Self::DumpsGet),
+            VERSION => Some(Self::Version),
+            _otherwise => None,
+        }
+    }
+
+    pub fn repr(&self) -> u8 {
+        use actions::*;
+        match self {
+            Self::All => 0,
+            Self::Search => SEARCH,
+            Self::DocumentsAdd => DOCUMENTS_ADD,
+            Self::DocumentsGet => DOCUMENTS_GET,
+            Self::DocumentsDelete => DOCUMENTS_DELETE,
+            Self::IndexesAdd => INDEXES_ADD,
+            Self::IndexesGet => INDEXES_GET,
+            Self::IndexesUpdate => INDEXES_UPDATE,
+            Self::IndexesDelete => INDEXES_DELETE,
+            Self::TasksGet => TASKS_GET,
+            Self::SettingsGet => SETTINGS_GET,
+            Self::SettingsUpdate => SETTINGS_UPDATE,
+            Self::StatsGet => STATS_GET,
+            Self::DumpsCreate => DUMPS_CREATE,
+            Self::DumpsGet => DUMPS_GET,
+            Self::Version => VERSION,
+        }
+    }
+}
+
+pub mod actions {
+    pub const SEARCH: u8 = 1;
+    pub const DOCUMENTS_ADD: u8 = 2;
+    pub const DOCUMENTS_GET: u8 = 3;
+    pub const DOCUMENTS_DELETE: u8 = 4;
+    pub const INDEXES_ADD: u8 = 5;
+    pub const INDEXES_GET: u8 = 6;
+    pub const INDEXES_UPDATE: u8 = 7;
+    pub const INDEXES_DELETE: u8 = 8;
+    pub const TASKS_GET: u8 = 9;
+    pub const SETTINGS_GET: u8 = 10;
+    pub const SETTINGS_UPDATE: u8 = 11;
+    pub const STATS_GET: u8 = 12;
+    pub const DUMPS_CREATE: u8 = 13;
+    pub const DUMPS_GET: u8 = 14;
+    pub const VERSION: u8 = 15;
+}

meilisearch-auth/src/error.rs

@@ -0,0 +1,41 @@
+use std::error::Error;
+
+use meilisearch_error::ErrorCode;
+use meilisearch_error::{internal_error, Code};
+use serde_json::Value;
+
+pub type Result<T> = std::result::Result<T, AuthControllerError>;
+
+#[derive(Debug, thiserror::Error)]
+pub enum AuthControllerError {
+    #[error("`{0}` field is mandatory.")]
+    MissingParameter(&'static str),
+    #[error("actions field value `{0}` is invalid. It should be an array of string representing action names.")]
+    InvalidApiKeyActions(Value),
+    #[error("indexes field value `{0}` is invalid. It should be an array of string representing index names.")]
+    InvalidApiKeyIndexes(Value),
+    #[error("expiresAt field value `{0}` is invalid. It should be in ISO-8601 format to represents a date or datetime in the future or specified as a null value. e.g. 'YYYY-MM-DD' or 'YYYY-MM-DDTHH:MM:SS'.")]
+    InvalidApiKeyExpiresAt(Value),
+    #[error("description field value `{0}` is invalid. It should be a string or specified as a null value.")]
+    InvalidApiKeyDescription(Value),
+    #[error("API key `{0}` not found.")]
+    ApiKeyNotFound(String),
+    #[error("Internal error: {0}")]
+    Internal(Box<dyn Error + Send + Sync + 'static>),
+}
+
+internal_error!(AuthControllerError: heed::Error, std::io::Error);
+
+impl ErrorCode for AuthControllerError {
+    fn error_code(&self) -> Code {
+        match self {
+            Self::MissingParameter(_) => Code::MissingParameter,
+            Self::InvalidApiKeyActions(_) => Code::InvalidApiKeyActions,
+            Self::InvalidApiKeyIndexes(_) => Code::InvalidApiKeyIndexes,
+            Self::InvalidApiKeyExpiresAt(_) => Code::InvalidApiKeyExpiresAt,
+            Self::InvalidApiKeyDescription(_) => Code::InvalidApiKeyDescription,
+            Self::ApiKeyNotFound(_) => Code::ApiKeyNotFound,
+            Self::Internal(_) => Code::Internal,
+        }
+    }
+}

meilisearch-auth/src/key.rs

@@ -0,0 +1,139 @@
+use crate::action::Action;
+use crate::error::{AuthControllerError, Result};
+use crate::store::{KeyId, KEY_ID_LENGTH};
+use chrono::{DateTime, Utc};
+use rand::Rng;
+use serde::{Deserialize, Serialize};
+use serde_json::{from_value, Value};
+
+#[derive(Debug, Deserialize, Serialize)]
+pub struct Key {
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub description: Option<String>,
+    pub id: KeyId,
+    pub actions: Vec<Action>,
+    pub indexes: Vec<String>,
+    pub expires_at: Option<DateTime<Utc>>,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
+
+impl Key {
+    pub fn create_from_value(value: Value) -> Result<Self> {
+        let description = value
+            .get("description")
+            .map(|des| {
+                from_value(des.clone())
+                    .map_err(|_| AuthControllerError::InvalidApiKeyDescription(des.clone()))
+            })
+            .transpose()?;
+
+        let id = generate_id();
+
+        let actions = value
+            .get("actions")
+            .map(|act| {
+                from_value(act.clone())
+                    .map_err(|_| AuthControllerError::InvalidApiKeyActions(act.clone()))
+            })
+            .ok_or(AuthControllerError::MissingParameter("actions"))??;
+
+        let indexes = value
+            .get("indexes")
+            .map(|ind| {
+                from_value(ind.clone())
+                    .map_err(|_| AuthControllerError::InvalidApiKeyIndexes(ind.clone()))
+            })
+            .ok_or(AuthControllerError::MissingParameter("indexes"))??;
+
+        let expires_at = value
+            .get("expiresAt")
+            .map(|exp| {
+                from_value(exp.clone())
+                    .map_err(|_| AuthControllerError::InvalidApiKeyExpiresAt(exp.clone()))
+            })
+            .transpose()?;
+
+        let created_at = Utc::now();
+        let updated_at = Utc::now();
+
+        Ok(Self {
+            description,
+            id,
+            actions,
+            indexes,
+            expires_at,
+            created_at,
+            updated_at,
+        })
+    }
+
+    pub fn update_from_value(&mut self, value: Value) -> Result<()> {
+        if let Some(des) = value.get("description") {
+            let des = from_value(des.clone())
+                .map_err(|_| AuthControllerError::InvalidApiKeyDescription(des.clone()));
+            self.description = des?;
+        }
+
+        if let Some(act) = value.get("actions") {
+            let act = from_value(act.clone())
+                .map_err(|_| AuthControllerError::InvalidApiKeyActions(act.clone()));
+            self.actions = act?;
+        }
+
+        if let Some(ind) = value.get("indexes") {
+            let ind = from_value(ind.clone())
+                .map_err(|_| AuthControllerError::InvalidApiKeyIndexes(ind.clone()));
+            self.indexes = ind?;
+        }
+
+        if let Some(exp) = value.get("expiresAt") {
+            let exp = from_value(exp.clone())
+                .map_err(|_| AuthControllerError::InvalidApiKeyExpiresAt(exp.clone()));
+            self.expires_at = exp?;
+        }
+
+        self.updated_at = Utc::now();
+
+        Ok(())
+    }
+
+    pub(crate) fn default_admin() -> Self {
+        Self {
+            description: Some("Default Admin API Key (Use it for all other operations. Caution! Do not use it on a public frontend)".to_string()),
+            id: generate_id(),
+            actions: vec![Action::All],
+            indexes: vec!["*".to_string()],
+            expires_at: None,
+            created_at: Utc::now(),
+            updated_at: Utc::now(),
+        }
+    }
+
+    pub(crate) fn default_search() -> Self {
+        Self {
+            description: Some(
+                "Default Search API Key (Use it to search from the frontend)".to_string(),
+            ),
+            id: generate_id(),
+            actions: vec![Action::Search],
+            indexes: vec!["*".to_string()],
+            expires_at: None,
+            created_at: Utc::now(),
+            updated_at: Utc::now(),
+        }
+    }
+}
+
+/// Generate a printable key of 64 characters using thread_rng.
+fn generate_id() -> [u8; KEY_ID_LENGTH] {
+    const CHARSET: &[u8] = b"abcdefghijklmnopqrstuvwxyz0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ";
+
+    let mut rng = rand::thread_rng();
+    let mut bytes = [0; KEY_ID_LENGTH];
+    for byte in bytes.iter_mut() {
+        *byte = CHARSET[rng.gen_range(0..CHARSET.len())];
+    }
+
+    bytes
+}

meilisearch-auth/src/lib.rs

@@ -0,0 +1,136 @@
+mod action;
+pub mod error;
+mod key;
+mod store;
+
+use std::path::Path;
+use std::str::from_utf8;
+use std::sync::Arc;
+
+use chrono::Utc;
+use serde_json::Value;
+use sha2::{Digest, Sha256};
+
+pub use action::{actions, Action};
+use error::{AuthControllerError, Result};
+pub use key::Key;
+use store::HeedAuthStore;
+
+#[derive(Clone)]
+pub struct AuthController {
+    store: Arc<HeedAuthStore>,
+    master_key: Option<String>,
+}
+
+impl AuthController {
+    pub fn new(db_path: impl AsRef<Path>, master_key: &Option<String>) -> Result<Self> {
+        let store = HeedAuthStore::new(db_path)?;
+
+        if store.is_empty()? {
+            generate_default_keys(&store)?;
+        }
+
+        Ok(Self {
+            store: Arc::new(store),
+            master_key: master_key.clone(),
+        })
+    }
+
+    pub async fn create_key(&self, value: Value) -> Result<Key> {
+        let key = Key::create_from_value(value)?;
+        self.store.put_api_key(key)
+    }
+
+    pub async fn update_key(&self, key: impl AsRef<str>, value: Value) -> Result<Key> {
+        let mut key = self.get_key(key).await?;
+        key.update_from_value(value)?;
+        self.store.put_api_key(key)
+    }
+
+    pub async fn get_key(&self, key: impl AsRef<str>) -> Result<Key> {
+        self.store
+            .get_api_key(&key)?
+            .ok_or_else(|| AuthControllerError::ApiKeyNotFound(key.as_ref().to_string()))
+    }
+
+    pub fn get_key_filters(&self, key: impl AsRef<str>) -> Result<AuthFilter> {
+        let mut filters = AuthFilter::default();
+        if self
+            .master_key
+            .as_ref()
+            .map_or(false, |master_key| master_key != key.as_ref())
+        {
+            let key = self
+                .store
+                .get_api_key(&key)?
+                .ok_or_else(|| AuthControllerError::ApiKeyNotFound(key.as_ref().to_string()))?;
+
+            if !key.indexes.iter().any(|i| i.as_str() == "*") {
+                filters.indexes = Some(key.indexes);
+            }
+        }
+
+        Ok(filters)
+    }
+
+    pub async fn list_keys(&self) -> Result<Vec<Key>> {
+        self.store.list_api_keys()
+    }
+
+    pub async fn delete_key(&self, key: impl AsRef<str>) -> Result<()> {
+        if self.store.delete_api_key(&key)? {
+            Ok(())
+        } else {
+            Err(AuthControllerError::ApiKeyNotFound(
+                key.as_ref().to_string(),
+            ))
+        }
+    }
+
+    pub fn get_master_key(&self) -> Option<&String> {
+        self.master_key.as_ref()
+    }
+
+    pub fn authenticate(&self, token: &[u8], action: Action, index: Option<&[u8]>) -> Result<bool> {
+        if let Some(master_key) = &self.master_key {
+            if let Some((id, exp)) = self
+                .store
+                // check if the key has access to all indexes.
+                .get_expiration_date(token, action, None)?
+                .or(match index {
+                    // else check if the key has access to the requested index.
+                    Some(index) => self.store.get_expiration_date(token, action, Some(index))?,
+                    // or to any index if no index has been requested.
+                    None => self.store.prefix_first_expiration_date(token, action)?,
+                })
+            {
+                let id = from_utf8(&id).map_err(|e| AuthControllerError::Internal(Box::new(e)))?;
+                if exp.map_or(true, |exp| Utc::now() < exp)
+                    && generate_key(master_key.as_bytes(), id).as_bytes() == token
+                {
+                    return Ok(true);
+                }
+            }
+        }
+
+        Ok(false)
+    }
+}
+
+#[derive(Default)]
+pub struct AuthFilter {
+    pub indexes: Option<Vec<String>>,
+}
+
+pub fn generate_key(master_key: &[u8], uid: &str) -> String {
+    let key = [uid.as_bytes(), master_key].concat();
+    let sha = Sha256::digest(&key);
+    format!("{}{:x}", uid, sha)
+}
+
+fn generate_default_keys(store: &HeedAuthStore) -> Result<()> {
+    store.put_api_key(Key::default_admin())?;
+    store.put_api_key(Key::default_search())?;
+
+    Ok(())
+}

meilisearch-auth/src/store.rs

@@ -0,0 +1,234 @@
+use enum_iterator::IntoEnumIterator;
+use std::borrow::Cow;
+use std::convert::TryFrom;
+use std::convert::TryInto;
+use std::fs::create_dir_all;
+use std::path::Path;
+use std::str;
+
+use chrono::{DateTime, Utc};
+use heed::types::{ByteSlice, DecodeIgnore, SerdeJson};
+use heed::{Database, Env, EnvOpenOptions, RwTxn};
+
+use super::error::Result;
+use super::{Action, Key};
+
+const AUTH_STORE_SIZE: usize = 1_073_741_824; //1GiB
+pub const KEY_ID_LENGTH: usize = 8;
+const AUTH_DB_PATH: &str = "auth";
+const KEY_DB_NAME: &str = "api-keys";
+const KEY_ID_ACTION_INDEX_EXPIRATION_DB_NAME: &str = "keyid-action-index-expiration";
+
+pub type KeyId = [u8; KEY_ID_LENGTH];
+
+#[derive(Clone)]
+pub struct HeedAuthStore {
+    env: Env,
+    keys: Database<ByteSlice, SerdeJson<Key>>,
+    action_keyid_index_expiration: Database<KeyIdActionCodec, SerdeJson<Option<DateTime<Utc>>>>,
+}
+
+impl HeedAuthStore {
+    pub fn new(path: impl AsRef<Path>) -> Result<Self> {
+        let path = path.as_ref().join(AUTH_DB_PATH);
+        create_dir_all(&path)?;
+        let mut options = EnvOpenOptions::new();
+        options.map_size(AUTH_STORE_SIZE); // 1GB
+        options.max_dbs(2);
+        let env = options.open(path)?;
+        let keys = env.create_database(Some(KEY_DB_NAME))?;
+        let action_keyid_index_expiration =
+            env.create_database(Some(KEY_ID_ACTION_INDEX_EXPIRATION_DB_NAME))?;
+        Ok(Self {
+            env,
+            keys,
+            action_keyid_index_expiration,
+        })
+    }
+
+    pub fn is_empty(&self) -> Result<bool> {
+        let rtxn = self.env.read_txn()?;
+
+        Ok(self.keys.len(&rtxn)? == 0)
+    }
+
+    pub fn put_api_key(&self, key: Key) -> Result<Key> {
+        let mut wtxn = self.env.write_txn()?;
+        self.keys.put(&mut wtxn, &key.id, &key)?;
+
+        let id = key.id;
+        // delete key from inverted database before refilling it.
+        self.delete_key_from_inverted_db(&mut wtxn, &id)?;
+        // create inverted database.
+        let db = self.action_keyid_index_expiration;
+
+        let actions = if key.actions.contains(&Action::All) {
+            // if key.actions contains All, we iterate over all actions.
+            Action::into_enum_iter().collect()
+        } else {
+            key.actions.clone()
+        };
+
+        let no_index_restriction = key.indexes.contains(&"*".to_owned());
+        for action in actions {
+            if no_index_restriction {
+                // If there is no index restriction we put None.
+                db.put(&mut wtxn, &(&id, &action, None), &key.expires_at)?;
+            } else {
+                // else we create a key for each index.
+                for index in key.indexes.iter() {
+                    db.put(
+                        &mut wtxn,
+                        &(&id, &action, Some(index.as_bytes())),
+                        &key.expires_at,
+                    )?;
+                }
+            }
+        }
+
+        wtxn.commit()?;
+
+        Ok(key)
+    }
+
+    pub fn get_api_key(&self, key: impl AsRef<str>) -> Result<Option<Key>> {
+        let rtxn = self.env.read_txn()?;
+        match try_split_array_at::<_, KEY_ID_LENGTH>(key.as_ref().as_bytes()) {
+            Some((id, _)) => self.keys.get(&rtxn, id).map_err(|e| e.into()),
+            None => Ok(None),
+        }
+    }
+
+    pub fn delete_api_key(&self, key: impl AsRef<str>) -> Result<bool> {
+        let mut wtxn = self.env.write_txn()?;
+        let existing = match try_split_array_at(key.as_ref().as_bytes()) {
+            Some((id, _)) => {
+                let existing = self.keys.delete(&mut wtxn, id)?;
+                self.delete_key_from_inverted_db(&mut wtxn, id)?;
+                existing
+            }
+            None => false,
+        };
+        wtxn.commit()?;
+
+        Ok(existing)
+    }
+
+    pub fn list_api_keys(&self) -> Result<Vec<Key>> {
+        let mut list = Vec::new();
+        let rtxn = self.env.read_txn()?;
+        for result in self.keys.remap_key_type::<DecodeIgnore>().iter(&rtxn)? {
+            let (_, content) = result?;
+            list.push(content);
+        }
+        Ok(list)
+    }
+
+    pub fn get_expiration_date(
+        &self,
+        key: &[u8],
+        action: Action,
+        index: Option<&[u8]>,
+    ) -> Result<Option<(KeyId, Option<DateTime<Utc>>)>> {
+        let rtxn = self.env.read_txn()?;
+        match try_split_array_at::<_, KEY_ID_LENGTH>(key) {
+            Some((id, _)) => {
+                let tuple = (id, &action, index);
+                Ok(self
+                    .action_keyid_index_expiration
+                    .get(&rtxn, &tuple)?
+                    .map(|expiration| (*id, expiration)))
+            }
+            None => Ok(None),
+        }
+    }
+
+    pub fn prefix_first_expiration_date(
+        &self,
+        key: &[u8],
+        action: Action,
+    ) -> Result<Option<(KeyId, Option<DateTime<Utc>>)>> {
+        let rtxn = self.env.read_txn()?;
+        match try_split_array_at::<_, KEY_ID_LENGTH>(key) {
+            Some((id, _)) => {
+                let tuple = (id, &action, None);
+                Ok(self
+                    .action_keyid_index_expiration
+                    .prefix_iter(&rtxn, &tuple)?
+                    .next()
+                    .transpose()?
+                    .map(|(_, expiration)| (*id, expiration)))
+            }
+            None => Ok(None),
+        }
+    }
+
+    fn delete_key_from_inverted_db(&self, wtxn: &mut RwTxn, key: &KeyId) -> Result<()> {
+        let mut iter = self
+            .action_keyid_index_expiration
+            .remap_types::<ByteSlice, DecodeIgnore>()
+            .prefix_iter_mut(wtxn, key)?;
+        while iter.next().transpose()?.is_some() {
+            // safety: we don't keep references from inside the LMDB database.
+            unsafe { iter.del_current()? };
+        }
+
+        Ok(())
+    }
+}
+
+/// Codec allowing to retrieve the expiration date of an action,
+/// optionnally on a spcific index, for a given key.
+pub struct KeyIdActionCodec;
+
+impl<'a> heed::BytesDecode<'a> for KeyIdActionCodec {
+    type DItem = (KeyId, Action, Option<&'a [u8]>);
+
+    fn bytes_decode(bytes: &'a [u8]) -> Option<Self::DItem> {
+        let (key_id, action_bytes) = try_split_array_at(bytes)?;
+        let (action_bytes, index) = match try_split_array_at(action_bytes)? {
+            (action, []) => (action, None),
+            (action, index) => (action, Some(index)),
+        };
+        let action = Action::from_repr(u8::from_be_bytes(*action_bytes))?;
+
+        Some((*key_id, action, index))
+    }
+}
+
+impl<'a> heed::BytesEncode<'a> for KeyIdActionCodec {
+    type EItem = (&'a KeyId, &'a Action, Option<&'a [u8]>);
+
+    fn bytes_encode((key_id, action, index): &Self::EItem) -> Option<Cow<[u8]>> {
+        let mut bytes = Vec::new();
+
+        bytes.extend_from_slice(*key_id);
+        let action_bytes = u8::to_be_bytes(action.repr());
+        bytes.extend_from_slice(&action_bytes);
+        if let Some(index) = index {
+            bytes.extend_from_slice(index);
+        }
+
+        Some(Cow::Owned(bytes))
+    }
+}
+
+/// Divides one slice into two at an index, returns `None` if mid is out of bounds.
+pub fn try_split_at<T>(slice: &[T], mid: usize) -> Option<(&[T], &[T])> {
+    if mid <= slice.len() {
+        Some(slice.split_at(mid))
+    } else {
+        None
+    }
+}
+
+/// Divides one slice into an array and the tail at an index,
+/// returns `None` if `N` is out of bounds.
+pub fn try_split_array_at<T, const N: usize>(slice: &[T]) -> Option<(&[T; N], &[T])>
+where
+    [T; N]: for<'a> TryFrom<&'a [T]>,
+{
+    let (head, tail) = try_split_at(slice, N)?;
+    let head = head.try_into().ok()?;
+    Some((head, tail))
+}